std::philox_engine

Defined in header `<random>`
template< class UIntType, std::size_t w, std::size_t n, std::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

[edit] 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, $2 w$ ).

This sequence represents a large unsigned integer counter value $Z=\sum n-1 j=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.

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

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

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$

[edit] 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>[edit]
`philox4x64` (C++26)	std::philox_engine<std::uint_fast64_t, 64, 4, 10, 0xD2E7470EE14C6C93, 0x9E3779B97F4A7C15, 0xCA5A826395121157, 0xBB67AE8584CAA73B>[edit]

[edit] Nested types

Type	Definition
`result_type`	`UIntType`

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

[edit] Member functions

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

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

[edit] Notes

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

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

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

std::philox_engine

Contents

[edit] Template parameters

[edit] Generator properties

[edit] Generating random values

[edit] Updating the output sequence

[edit] Predefined specializations

[edit] Nested types

[edit] Data members

[edit] Member functions

Construction and Seeding

Generation

Characteristics

[edit] Non-member functions

[edit] Notes

[edit] Example

Navigation

Toolbox