std::philox_engine

template<
    class UIntType, std::size_t w, std::size_t n, std::size_t r,
    UIntType... consts
>
class philox_engine;

std::philox_engine is a counter-based random number engine.

Template parameters

If any of the following values is not true, the program is ill-formed:

• sizeof...(consts) == n
• n == 2 || n == 4
• 0 < r
• 0 < w && w <= std::numeric_limits<UIntType>::digits

Generator properties

In the following description, let \(\scriptsize Q_i \)Q_i denote the ith element of sequence Q, where the subscript starts from zero.

The size of the states of philox_engine is \(\scriptsize O(n)\)O(n), each of them consists of four parts:

• A sequence X of n integer values, where each value is in [0, 2w).
• This sequence represents a large unsigned integer counter value \(\scriptsize Z=\sum_{j=0}^{n-1} X \cdot 2^{wj} \)Z=∑_n-1j=0X⋅2^wj of \(\scriptsize n \cdot w \)n⋅w bits.
• A sequence K of n / 2 keys of type UIntType.
• A buffer Y of n produced values of type UIntType.
• An index j in Y buffer.

The transition algorithm of philox_engine (\(\scriptsize TA(X_i) \)TA(X_i)) is defined as follows:

• If j is not n - 1, increments j by 1.^[1]
• If j is n - 1, performs the following operations:^[2]

1. Generates a new sequence of n random values (see below) and stores them in Y.
2. Increments the counter Z by 1.
3. Resets j to 0.

The generation algorithm of philox_engine is \(\scriptsize GA(X_i)=Y_j \)GA(X_i)=Y_j.

Generating random values

Random values are generated from the following parameters:

• the number of rounds r
• the current counter sequence X
• the key sequence K
• the multiplier sequence M
• the round constant sequence C

The sequences M and C are formed from the values from template parameter pack consts, which represents the \(\scriptsize M_k \)M_k and \(\scriptsize C_k \)C_k constants as [\(\scriptsize M_0 \)M₀,\(\scriptsize C_0 \)C₀,\(\scriptsize M_1 \)M₁,\(\scriptsize C_1 \)C₁,... , ...,\(\scriptsize M_{n/2-1} \)M_n/2-1,\(\scriptsize C_{n/2-1} \)C_n/2-1].

Random numbers are generated by the following process:

1. Initializes the output sequence S with the elements of X.
2. Updates the elements of S for r rounds.
3. Replaces the values in the buffer Y with the values in S.

Updating the output sequence

For each round of update, an intermediate sequence V is initialized with the elements of S in a specified order:

Given the following operation notations:

• \(\scriptsize \mathsf{xor} \)xor, built-in bitwise XOR.
• \(\scriptsize \mathsf{mullo} \)mullo, it calcuates the low half of modular multiplication and is defined as \(\scriptsize \mathsf{mullo}(a,b,w)=(a \cdot b) \mod 2^w \)mullo(a,b,w)=(a⋅b) mod 2^w.
• \(\scriptsize \mathsf{mulhi} \)mulhi, it calcuates the high half of multiplication and is defined as \(\scriptsize \mathsf{mulhi}(a,b,w)=\left\lfloor (a \cdot b)/2^w \right\rfloor \)mulhi(a,b,w)=⌊(a⋅b)/2^w⌋.

Let q be the current round number (starting from zero), for each integer k in [0, n / 2), the elements of the output sequence S are updated as follows:

• \(\scriptsize X_{2 \cdot k}=\mathsf{mulhi}(V_{2 \cdot k},M_k,w)\ \mathsf{xor}\ ((K_k+q \cdot C_k) \mod 2^w)\ \mathsf{xor}\ V_{2 \cdot k+1} \)X_2⋅k=mulhi(V_2⋅k,M_k,w) xor ((K_k+q⋅C_k) mod 2^w) xor V_2⋅k+1
• \(\scriptsize X_{2 \cdot k+1}=\mathsf{mullo}(V_{2 \cdot k},M_k,w) \)X_2⋅k+1=mullo(V_2⋅k,M_k,w)

Predefined specializations

The following specializations define the random number engine with two commonly used parameter sets:

Nested types

Data members

Member functions

Non-member functions

Notes

Example