Difference between revisions of "cpp/numeric/random/philox engine"

Revision as of 03:43, 22 August 2024

Defined in header `<random>`
template< class UIntType, size_t w, size_t n, size_t r, UIntType... consts > class philox_engine;		(since C++26)

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

UIntType	-	The result type generated by the generator. The effect is undefined if this is not one of unsigned short, unsigned int, unsigned long, or unsigned long long.
w	-	the word size in bits
n	-	the word count
r	-	the round count
consts	-	the sequence of multipliers and round constants used for generating random numbers

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

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

Generator properties

In the following description, let $\scriptsize X_i $ $X i$ denote the ith element of sequence X, 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 Z of n integer values, where each value is in [0, $2 w$ ).

This sequence represents a large unsigned integer counter value $Z=\sum n-1j=0 X\cdot2 wj$ of $\scriptsize n \cdot w $ $n\cdotw$ 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]

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

The generation algorithm of philox_engine is $\scriptsize GA(X_i)=Y_j $ $GA(X i)=Y j$ .

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

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 0$ , $\scriptsize C_0 $ $C 0$ , $\scriptsize M_1 $ $M 1$ , $\scriptsize C_1 $ $C 1$ ,... , ..., $\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:

Initializes the output sequence S with the elements of X.
Updates the elements of S for r rounds.
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:

n	$\scriptsize V_0 $ $V 0$	$\scriptsize V_1 $ $V 1$	$\scriptsize V_2 $ $V 2$	$\scriptsize V_3 $ $V 3$	$\scriptsize V_4 $ $V 4$	$\scriptsize V_5 $ $V 5$	$\scriptsize V_6 $ $V 6$	$\scriptsize V_7 $ $V 7$	$\scriptsize V_8 $ $V 8$	$\scriptsize V_9 $ $V 9$	$\scriptsize V_{10} $ $V 10$	$\scriptsize V_{11} $ $V 11$	$\scriptsize V_{12} $ $V 12$	$\scriptsize V_{13} $ $V 13$	$\scriptsize V_{14} $ $V 14$	$\scriptsize V_{15} $ $V 15$
2	$\scriptsize S_0 $ $S 0$	$\scriptsize S_1 $ $S 1$	N/A
4	$\scriptsize S_0 $ $S 0$	$\scriptsize S_3 $ $S 3$	$\scriptsize S_2 $ $S 2$	$\scriptsize S_1 $ $S 1$	N/A
8	$\scriptsize S_2 $ $S 2$	$\scriptsize S_1 $ $S 1$	$\scriptsize S_4 $ $S 4$	$\scriptsize S_7 $ $S 7$	$\scriptsize S_6 $ $S 6$	$\scriptsize S_5 $ $S 5$	$\scriptsize S_0 $ $S 0$	$\scriptsize S_3 $ $S 3$	N/A
16	$\scriptsize S_0 $ $S 0$	$\scriptsize S_9 $ $S 9$	$\scriptsize S_2 $ $S 2$	$\scriptsize S_{13} $ $S 13$	$\scriptsize S_6 $ $S 6$	$\scriptsize S_{11} $ $S 11$	$\scriptsize S_4 $ $S 4$	$\scriptsize S_{15} $ $S 15$	$\scriptsize S_{10} $ $S 10$	$\scriptsize S_7 $ $S 7$	$\scriptsize S_{12} $ $S 12$	$\scriptsize S_3 $ $S 3$	$\scriptsize S_{14} $ $S 14$	$\scriptsize S_5 $ $S 5$	$\scriptsize S_8 $ $S 8$	$\scriptsize S_1 $ $S 1$

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 $mullo(a,b,w)=(a\cdotb) mod 2 w$ .
$\scriptsize \mathsf{mulhi} $ $mulhi$ , it calcuates the high half of multiplication and is defined as $mulhi(a,b,w)=⌊(a\cdotb)/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:

$X 2\cdotk =mullo(V 2\cdotk+1,M k,w)$
$X 2\cdotk+1 =mulhi(V 2\cdotk+1,M k,w) xor ((K k +q\cdotC k) mod 2 w) xor V 2\cdotk$

Predefined specializations

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

Defined in header `<random>`
Type	Definition
`philox4x32` (C++26)	std::philox_engine<std::uint_fast32_t, 32, 4, 10, 0xD2511F53, 0x9E3779B9, 0xCD9E8D57, 0xBB67AE85>
`philox4x64` (C++26)	std::philox_engine<std::uint_fast64_t, 64, 4, 10, 0xD2E7470EE14C6C93, 0x9E3779B97F4A7C15, 0xCA5A826395121157, 0xBB67AE8584CAA73B>

Nested types

Type	Definition
`result_type`	`UIntType`

Data members

constexpr std::size_t word_size [static]	w (public static member constant)
constexpr std::size_t word_count [static]	n (public static member constant)
constexpr std::size_t round_count [static]	r (public static member constant)
constexpr std::array<result_type, word_count / 2> multipliers [static]	the multiplier sequence M (public static member constant)
constexpr std::array<result_type, word_count / 2> round_consts [static]	the round constant sequence C (public static member constant)
constexpr std::uint_least32_t default_seed [static]	20111115u (public static member constant)

Member functions

Construction and Seeding
(constructor)	constructs the engine (public member function) [edit]
seed	sets the current state of the engine (public member function) [edit]
set_counter	sets the current counter of the engine (public member function) [edit]
Generation
operator()	advances the engine's state and returns the generated value (public member function) [edit]
discard	advances the engine's state by a specified amount (public member function) [edit]
Characteristics
min [static]	gets the smallest possible value in the output range (public static member function) [edit]
max [static]	gets the largest possible value in the output range (public static member function) [edit]

Non-member functions

operator== (C++26)	compares the internal states of two pseudo-random number engines (function) [edit]

operator<<operator>> (C++26)	performs stream input and output on pseudo-random number engine (function template) [edit]

Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_philox_engine`	202406L	(C++26)	`std::philox_engine`

Example

[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.

[1]

[2]

@@ Line 5: / Line 5: @@
 {{dcl|since=c++26|
 template< class UIntType, size_t w, size_t n, size_t r, UIntType... consts >
-class subtract_with_carry_engine;
+class philox_engine;
 }}
 {{dcl end}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
philox_engine::philox_engine
philox_engine::seed
philox_engine::set_counter
Generation
philox_engine::operator()
philox_engine::discard
Characteristics
philox_engine::min
philox_engine::max
Non-member functions
operator== (C++26)
operator<<operator>> (C++26)(C++26)

n	\(\scriptsize V_0 \) $V 0$	\(\scriptsize V_1 \) $V 1$	\(\scriptsize V_2 \) $V 2$	\(\scriptsize V_3 \) $V 3$	\(\scriptsize V_4 \) $V 4$	\(\scriptsize V_5 \) $V 5$	\(\scriptsize V_6 \) $V 6$	\(\scriptsize V_7 \) $V 7$	\(\scriptsize V_8 \) $V 8$	\(\scriptsize V_9 \) $V 9$	\(\scriptsize V_{10} \) $V 10$	\(\scriptsize V_{11} \) $V 11$	\(\scriptsize V_{12} \) $V 12$	\(\scriptsize V_{13} \) $V 13$	\(\scriptsize V_{14} \) $V 14$	\(\scriptsize V_{15} \) $V 15$
2	\(\scriptsize S_0 \) $S 0$	\(\scriptsize S_1 \) $S 1$	N/A
4	\(\scriptsize S_0 \) $S 0$	\(\scriptsize S_3 \) $S 3$	\(\scriptsize S_2 \) $S 2$	\(\scriptsize S_1 \) $S 1$	N/A
8	\(\scriptsize S_2 \) $S 2$	\(\scriptsize S_1 \) $S 1$	\(\scriptsize S_4 \) $S 4$	\(\scriptsize S_7 \) $S 7$	\(\scriptsize S_6 \) $S 6$	\(\scriptsize S_5 \) $S 5$	\(\scriptsize S_0 \) $S 0$	\(\scriptsize S_3 \) $S 3$	N/A
16	\(\scriptsize S_0 \) $S 0$	\(\scriptsize S_9 \) $S 9$	\(\scriptsize S_2 \) $S 2$	\(\scriptsize S_{13} \) $S 13$	\(\scriptsize S_6 \) $S 6$	\(\scriptsize S_{11} \) $S 11$	\(\scriptsize S_4 \) $S 4$	\(\scriptsize S_{15} \) $S 15$	\(\scriptsize S_{10} \) $S 10$	\(\scriptsize S_7 \) $S 7$	\(\scriptsize S_{12} \) $S 12$	\(\scriptsize S_3 \) $S 3$	\(\scriptsize S_{14} \) $S 14$	\(\scriptsize S_5 \) $S 5$	\(\scriptsize S_8 \) $S 8$	\(\scriptsize S_1 \) $S 1$

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/numeric/random/philox engine"

Revision as of 03:43, 22 August 2024

Contents

Template parameters

Generator properties

Generating random values

Updating the output sequence

Predefined specializations

Nested types

Data members

Member functions

Construction and Seeding

Generation

Characteristics

Non-member functions

Notes

Example

Navigation

Toolbox