NAME¶

std::mersenne_twister_engine - std::mersenne_twister_engine

Synopsis¶

Defined in header <random>
template<

class UIntType, std::size_t w, std::size_t n, std::size_t m,
std::size_t r, (since C++11)
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;

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 \(\scriptsize {[0,2^w)}\)[0,
2w
).

Template parameters¶

The result type generated by the generator. The effect is
UIntType - 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 1^st to 7^th components of the bit-scrambling (tempering)
matrix
f - the initialization multiplier

If any of the following restriction 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\)X
j stands for the \(j\mod n\)j mod nth value (starting from 0) of X.

Given the following bitwise operation notations:

* \(\mathsf{bitand}\)bitand, built-in bitwise AND.
* \(\mathsf{xor}\)xor, built-in bitwise XOR.
* \(\mathsf{lshift}\)lshift, built-in bitwise left-shift.
* \(\mathsf{rshift}\)rshift, built-in bitwise right-shift.

The transition algorithm of mersenne_twister_engine (\(TA(x_i)\)TA(x
i)) is defined as follows:

1. Concatenate the upper w - r bits of \(X_{i-n}\)X
i-n with the lower r bits of \(X_{i+1-n}\)X
i+1-n to obtain an unsigned integer value Y.
2. Let y be \(a \cdot (Y\ \mathsf{bitand}\ 1)\)a·(Y bitand 1), and set \(X_i\)X
i to \(X_{i+m−n}\ \mathsf{xor}\ (Y\ \mathsf{rshift}\ 1)\ \mathsf{xor}\ y\)X
i+m−n xor (Y rshift 1) xor y.

The generation algorithm of mersenne_twister_engine (\(GA(x_i)\)GA(x
i)) is defined as follows:

1. Let \(z_1\)z
1 be \(X_i\ \mathsf{xor}\ ((X_i\ \mathsf{rshift}\ u)\ \mathsf{bitand}\ d)\)X
i xor ((X
i rshift u) bitand d).
2. Let \(z_2\)z
2 be \(z_1\ \mathsf{xor}\ (((z_1\ \mathsf{lshift}\ s)\mod 2^w)\ \mathsf{bitand}\
b)\)X
i xor (((X
i lshift s) mod 2w
) bitand b).
3. Let \(z_3\)z
3 be \(z_2\ \mathsf{xor}\ (((z_2\ \mathsf{lshift}\ t)\mod 2^w)\ \mathsf{bitand}\
c)\)X
i xor (((X
i lshift t) mod 2w
) bitand c).
4. Let \(z_4\)z
4 be \(z_3\ \mathsf{xor}\ (z_3\ \mathsf{rshift}\ l)\)z
3 xor (z
3 rshift l).
5. Deliver \(z_4\)z
4 as the result (i.e. \(GA(x_i)=z_4\)GA(x
i)=z
4).

Predefined specializations

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

Defined in header <random>
Type Definition
std::mersenne_twister_engine<std::uint_fast32_t,
32, 624, 397, 31,
0x9908b0df, 11,
mt19937 (C++11) 0xffffffff, 7,
0x9d2c5680, 15,
0xefc60000, 18, 1812433253>
32-bit Mersenne Twister by Matsumoto and Nishimura, 1998
std::mersenne_twister_engine<std::uint_fast64_t,
64, 312, 156, 31,
0xb5026f5aa96619e9, 29,
mt19937_64 (C++11) 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 w
[static] (public static member constant)
constexpr size_t state_size n
[static] (public static member constant)
constexpr size_t shift_size m
[static] (public static member constant)
constexpr size_t mask_bits r
[static] (public static member constant)
constexpr UIntType xor_mask a
[static] (public static member constant)
constexpr size_t tempering_u u
[static] (public static member constant)
constexpr UIntType tempering_d d
[static] (public static member constant)
constexpr size_t tempering_s s
[static] (public static member constant)
constexpr UIntType tempering_b b
[static] (public static member constant)
constexpr size_t tempering_t t
[static] (public static member constant)
constexpr UIntType tempering_c c
[static] (public static member constant)
constexpr size_t tempering_l l
[static] (public static member constant)
constexpr UIntType initialization_multiplier f
[static] (public static member constant)
constexpr UIntType default_seed 5489u
[static] (public static member constant)

Member functions¶

Construction and Seeding¶

constructor constructs the engine
(C++11) (public member function)
seed sets the current state of the engine
(C++11) (public member function)

Generation¶

operator() advances the engine's state and returns the generated value
(C++11) (public member function)
discard advances the engine's state by a specified amount
(C++11) (public member function)

Characteristics¶

min gets the smallest possible value in the output range
[static] (C++11) (public static member function)
max gets the largest possible value in the output range
[static] (C++11) (public static member function)

Non-member functions¶

operator== compares the internal states of two pseudo-random number
operator!= engines
(C++11) (function)
(C++11)(removed in C++20)
operator<< performs stream input and output on pseudo-random number
operator>> engine
(C++11) (function template)

Notes¶

The N^th consecutive invocation of a default-constructed engine is required to
produce the following value:

N The random engine type The value to produce
10000 std::mt19937 4123659995
10000 std::mt19937_64 9981545732273789042

This is to guarantee that the random engine is conforming to the standard (see
N1398).

// Run this code

#include <cassert>
#include <random>

int main()
{
std::mt19937 gen32;
std::mt19937_64 gen64;

gen32.discard(10000 - 1);
gen64.discard(10000 - 1);

assert(gen32() == 4123659995);
assert(gen64() == 9981545732273789042ull);
}