std::philox_engine - cppreference.com (original) (raw)

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

Contents

• 1 Template parameters
• 2 Generator properties
  • 2.1 Generating random values
  • 2.2 Updating the output sequence
• 3 Predefined specializations
• 4 Nested types
• 5 Data members
• 6 Member functions
  • 6.1 Construction and Seeding
  • 6.2 Generation
  • 6.3 Characteristics
• 7 Non-member functions
• 8 Notes
• 9 Example

[edit] 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

[edit] Generator properties

In the following description, let \(\scriptsize Q_i \)Qi 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​, 2 w
).

• This sequence represents a large unsigned integer counter value \(\scriptsize Z=\sum_{j=0}^{n-1} X \cdot 2^{wj} \)Z=∑n-1
  j=0X⋅2wj
  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(Xi)) 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(Xi)=Yj.

1. ↑ In this case, the next generation algorithm call returns the next generated value in the buffer.
2. ↑ In this case, the buffer is refreshed, and the next generation algorithm call returns the first value in the new buffer.

[edit] 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 \)Mk and \(\scriptsize C_k \)Ck constants as [\(\scriptsize M_0 \)M0, \(\scriptsize C_0 \)C0, \(\scriptsize M_1 \)M1, \(\scriptsize C_1 \)C1,... , ..., \(\scriptsize M_{n/2-1} \)Mn/2-1, \(\scriptsize C_{n/2-1} \)Cn/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.

[edit] 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 2w
  .
• \(\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)/2w
  ⌋.

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} \)X2⋅k=mulhi(V2⋅k,Mk,w) xor ((Kk+q⋅Ck) mod 2w
  ) xor V2⋅k+1
• \(\scriptsize X_{2 \cdot k+1}=\mathsf{mullo}(V_{2 \cdot k},M_k,w) \)X2⋅k+1=mullo(V2⋅k,Mk,w)

[edit] Predefined specializations

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

[edit] Nested types

[edit] Data members

[edit] Member functions

[edit] Non-member functions

| | compares the internal states of two pseudo-random number engines (function) [edit] | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | performs stream input and output on pseudo-random number engine (function template) [edit] |

[edit] Notes

[edit] Example