# std::mersenne_twister_engine

> C++ Atlas: `cppatlas.com/w/cpp/numeric/random/mersenne_twister_engine` | Source: https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine | Domain: Numerics | Standards: C++11, C++20

mersenne_twister_engine is a random number engine based on Mersenne Twister algorithm. It produces high quality, but not cryptographically secure, unsigned integer random numbers of type UIntType on the interval [0, 2w).

## Official Specification Summary (cppreference)

```cpp
// Defined in header <random>

template<
    class UIntType, std::size_t w, std::size_t n, std::size_t m, std::size_t r,
    UIntType a, std::size_t u, UIntType d, std::size_t s,
    UIntType b, std::size_t t, UIntType c, std::size_t l, UIntType f
> class mersenne_twister_engine; // (since C++11)
```

`mersenne_twister_engine` is a random number engine based on Mersenne Twister algorithm. It produces high quality, but not cryptographically secure, unsigned integer random numbers of type `UIntType` on the interval [0, 2^(w)).

### 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 power of two that determines the range of values generated by the engine
- `n` - the degree of recurrence
- `m` - the middle word, an offset used in the recurrence relation defining the state
- `r` - the number of bits of the lower bit-mask, also known as the twist value
- `a` - the conditional xor-mask, i.e. the coefficients of the rational normal form twist matrix
- `u, d, s, b, t, c, l` - the 1st to 7th components of the bit-scrambling (tempering) matrix
- `f` - the initialization multiplier

If any of the following restrictions is violated, the program is ill-formed:

- `m` is in `[1,` `n]`.
- The following expressions are all `true`:

  - `w >= 3`
  - `w >= r`
  - `w >= u`
  - `w >= s`
  - `w >= t`
  - `w >= l`
  - `w <= std::numeric_limits<UIntType>::digits`

- Given `(1u << w) - 1u` as `w1`, the following expressions are all `true`:

  - `a <= w1`
  - `b <= w1`
  - `c <= w1`
  - `d <= w1`
  - `f <= w1`

### Generator properties

The size of the states of `mersenne_twister_engine` is `n`, each of them consists of a sequence `X` of `n` values of type `result_type`. X^(j) stands for the j mod nth value (starting from 0) of `X`.

Given the following bitwise operation notations:

- bitand, built-in bitwise AND.
- xor, built-in bitwise XOR.
- lshift, built-in bitwise left-shift.
- rshift, built-in bitwise right-shift.

The transition algorithm of `mersenne_twister_engine` (TA(xⁱ)) is defined as follows:

1. Concatenate the upper `w - r` bits of Xⁱ⁻ⁿ with the lower `r` bits of Xⁱ⁺¹⁻ⁿ to obtain an unsigned integer value `Y`.
2. Let `y` be a·(Y bitand 1), and set Xⁱ to X^(i+m−n) xor (Y rshift 1) xor y.

The generation algorithm of `mersenne_twister_engine` (GA(xⁱ)) is defined as follows:

1. Let z¹ be Xⁱ xor ((Xⁱ rshift u) bitand d).
2. Let z² be Xⁱ xor (((Xⁱ lshift s) mod 2^(w)) bitand b).
3. Let z³ be Xⁱ xor (((Xⁱ lshift t) mod 2^(w)) bitand c).
4. Let z⁴ be z³ xor (z³ rshift l).
5. Deliver z⁴ as the result (i.e. GA(xⁱ)=z⁴).

### Predefined specializations

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

Defined in header `<random>`

**Type — Definition**

- `mt19937` (C++11): `std::mersenne_twister_engine<std::uint_fast32_t,` `32, 624, 397, 31,` `0x9908b0df, 11,` `0xffffffff, 7,` `0x9d2c5680, 15,` `0xefc60000, 18, 1812433253>` 32-bit Mersenne Twister by Matsumoto and Nishimura, 1998
- `mt19937_64` (C++11): `std::mersenne_twister_engine<std::uint_fast64_t,` `64, 312, 156, 31,` `0xb5026f5aa96619e9, 29,` `0x5555555555555555, 17,` `0x71d67fffeda60000, 37,` `0xfff7eee000000000, 43,` `6364136223846793005>` 64-bit Mersenne Twister by Matsumoto and Nishimura, 2000

### Nested types

**Type — Definition**

- `result_type`: `UIntType`

### Data members

- `constexpr size_t word_size` [static]: `w` (public static member constant)
- `constexpr size_t state_size` [static]: `n` (public static member constant)
- `constexpr size_t shift_size` [static]: `m` (public static member constant)
- `constexpr size_t mask_bits` [static]: `r` (public static member constant)
- `constexpr UIntType xor_mask` [static]: `a` (public static member constant)
- `constexpr size_t tempering_u` [static]: `u` (public static member constant)
- `constexpr UIntType tempering_d` [static]: `d` (public static member constant)
- `constexpr size_t tempering_s` [static]: `s` (public static member constant)
- `constexpr UIntType tempering_b` [static]: `b` (public static member constant)
- `constexpr size_t tempering_t` [static]: `t` (public static member constant)
- `constexpr UIntType tempering_c` [static]: `c` (public static member constant)
- `constexpr size_t tempering_l` [static]: `l` (public static member constant)
- `constexpr UIntType initialization_multiplier` [static]: `f` (public static member constant)
- `constexpr UIntType default_seed` [static]: `5489u` (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)

**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++11), `operator!=` (C++11)(removed in C++20): compares the internal states of two pseudo-random number engines (function)
- `operator<<` (C++11), `operator>>`: performs stream input and output on pseudo-random number engine (function template)

### Example

> Note: This section is incomplete Reason: no example

---
Attribution: content from https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_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.