PhiloxRandom

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	x
Atlas A2 training product/Atlas A2 inference product	x
Atlas 200I/500 A2 inference product	x
Atlas inference product AI Core	x
Atlas inference product Vector Core	x
Atlas training product	x

Function Usage

Generates several random numbers based on the Philox random number generation algorithm after a random number seed is given.

The core algorithm for Philox random number generation is a counter-based pseudo-random number generation algorithm. The input is a 128-bit counter C, two 32-bit keys (k0 and k1), and the output is four 32-bit integers.

Prototype

Continuous mode

template <uint16_t Rounds = 7, typename T>
__aicore__ inline void PhiloxRandom(const LocalTensor<T>& dstLocal, const PhiloxKey& philoxKey, const PhiloxCounter& philoxCounter, uint16_t count)

Stride mode

template <uint16_t Rounds = 7, typename T>
__aicore__ inline void PhiloxRandom(const LocalTensor<T>& dstLocal, const PhiloxKey& philoxKey, const PhiloxCounter& philoxCounter, const PhiloxRandomParams& params)

Parameters

**Table 1** Parameters in the template
Parameter	Description
Rounds	Number of iterations implemented in the Philox algorithm. The value can be 7 or 10.
T	Data type of the destination operand. The supported data types are uint32_t, int32_t, and float. uint32_t and int32_t indicate even distribution within the data type range, and float indicates even distribution within the range of 0–1.

Table 2 Parameters

Parameter

Input/Output

Description

dstLocal

Output

Destination operand.

The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT.

The start address of LocalTensor must be 32-byte aligned.

philoxKey

Input

Random seed. It indicates two 32-bit keys. The definition is as follows:

using PhiloxKey = uint32_t[2];

philoxCounter

Input

Random seed. It indicates a 128-bit counter C consisting of four 32-bit parts. The definition is as follows:

using PhiloxCounter = uint32_t[4];

count

Input

Number of elements for generating the destination operand.

params

Input

Parameter information required for calculation in the stride mode. The PhiloxRandomParams type is defined as follows:

struct PhiloxRandomParams {
   uint32_t stride;  // Spacing between two lines of elements.
   uint32_t row;     // Number of generated rows.
   uint32_t column;  // Number of elements in each row.
}

The value of row x column is greater than 0 and less than or equal to the size of LocalTensor.
column % 4 == 0, stride % 4 == 0, stride >= column.

Figure 1 PhiloxRandom

The preceding figure shows how to generate a random number.

In the continuous mode, set philoxCounter to {0, 0, 0, 0} and count to 32 to generate 32 random numbers.
In the stride mode, the data can be generated twice by column, and the API is called twice. In the first call, philoxCounter is set to {0, 0, 0, 0}, stride to 8, row to 4, and column to 4. In the second call, philoxCounter is set to {1, 0, 0, 0} (each time the counter C automatically increases, a 128-bit random number is generated), stride to 8, row to 4, and column to 4.

Returns

None

Restrictions

None

Examples

For details about the complete operator example, see philoxrandom operator sample.

// dstLocal: tensor for storing the computation result
// philoxKey={0,0}, philoxCounter={0,0,0,0}

// stride mode. 32 x 32 elements are generated.
PhiloxRandom<10>(dstLocal, philoxKey, philoxCounter, params);
// Contiguous mode. 1024 elements are generated.
PhiloxRandom<10>(dstLocal, philoxKey, philoxCounter, 1024);

Result example:

[0.31179297 0.8263413  0.6849456 ... 0.10521233 0.29894042 0.96700084]

Parent topic: Random Functions