# std::philox_engine

> C++ Atlas: `cppatlas.com/w/cpp/numeric/random/philox_engine` | Source: https://en.cppreference.com/w/cpp/numeric/random/philox_engine | Domain: Numerics | Standards: C++26

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

## Official Specification Summary (cppreference)

```cpp
// 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.

### Template parameters

- `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 Qⁱ denote the `i`th element of sequence `Q`, where the subscript starts from zero.

The size of the states of `philox_engine` is 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 Z=∑ⁿ⁻¹_(j=0)X⋅2^(wj) of 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` (TA(Xⁱ)) 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 GA(Xⁱ)=Y^(j).

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.

#### 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 M^(k) and C^(k) constants as `[`M⁰`,` C⁰`,` M¹`,` C¹`,...,...,` M^(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:

| `n` | V⁰ | V¹ | V² | V³ | V⁴ | V⁵ | V⁶ | V⁷ | V⁸ | V⁹ | V¹⁰ | V¹¹ | V¹² | V¹³ | V¹⁴ | V¹⁵ |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `2` | S⁰ | S¹ | N/A |   |   |   |   |   |   |   |   |   |   |   |   |   |
| `4` | S⁰ | S³ | S² | S¹ | N/A |   |   |   |   |   |   |   |   |   |   |   |
| `8` | S² | S¹ | S⁴ | S⁷ | S⁶ | S⁵ | S⁰ | S³ | N/A |   |   |   |   |   |   |   |
| `16` | S⁰ | S⁹ | S² | S¹³ | S⁶ | S¹¹ | S⁴ | S¹⁵ | S¹⁰ | S⁷ | S¹² | S³ | S¹⁴ | S⁵ | S⁸ | S¹ |

Given the following operation notations:

- xor, built-in bitwise XOR.
- mullo, it calcuates the low half of modular multiplication and is defined as mullo(a,b,w)=(a⋅b) mod 2^(w).
- mulhi, it calcuates the high half of multiplication and is defined as 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:

- X^(2⋅k)=mullo(V^(2⋅k+1),M^(k),w)
- X^(2⋅k+1)=mulhi(V^(2⋅k+1),M^(k),w) xor ((K^(k)+q⋅C^(k)) mod 2^(w)) xor V^(2⋅k)

### 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)
- `seed`: sets the current state of the engine (public member function)
- `set_counter`: sets the current counter of the engine (public member function)

**Generation**

- `operator()`: advances the engine's state and returns the generated value (public member function)
- `discard`: advances the engine's state by a specified amount (public member function)

**Characteristics**

- `min` [static]: gets the smallest possible value in the output range (public static member function)
- `max` [static]: gets the largest possible value in the output range (public static member function)

### Non-member functions

- `operator==` (C++26): compares the internal states of two pseudo-random number engines (function)
- `operator<<` (C++26), `operator>>`: performs stream input and output on pseudo-random number engine (function template)

### Notes

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

### Example

> Note: This section is incomplete Reason: no example

---
Attribution: content from https://en.cppreference.com/w/cpp/numeric/random/philox_engine (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.