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,
UIntType a, std::size_t u, UIntType d, std::size_t s, (since C++11)
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 unsigned integer random numbers of type UIntType
on the interval \(\scriptsize {[0,2^w)}\)[0, 2w
).

The following type aliases 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

Template parameters¶

The result type generated by the generator. The effect is undefined if
UIntType - 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
series x, 1 ≤ m < n
r - the number of bits of the lower bit-mask, 0 ≤ r ≤ w - 1, also known
as the twist value
a - the conditional xor-mask, i.e. the coefficients of the rational normal
form twist matrix
u - 1st component of the bit-scrambling (tempering) matrix
d - 2nd component of the bit-scrambling (tempering) matrix
s - 3rd component of the bit-scrambling (tempering) matrix
b - 4th component of the bit-scrambling (tempering) matrix
t - 5th component of the bit-scrambling (tempering) matrix
c - 6th component of the bit-scrambling (tempering) matrix
l - 7th component of the bit-scrambling (tempering) matrix
f - the initialization multiplier

The following relations shall hold:

0 < m <= n,

2 < w,
r <= w,
u <= w,
s <= w,
t <= w,
l <= w,
w <= std::numeric_limits<UIntType>::digits,
a <= 2^w-1,
b <= 2^w-1,
c <= 2^w-1,
d <= 2^w-1, and

f <= 2^w-1 (a^b denotes a to the power of b)

Member types¶

Member type Definition
result_type(C++11) The integral type, UIntType, generated by the engine. Results are
undefined if this is not an unsigned integral type.

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)

Member constants¶

constexpr size_t word_size the template parameter w, determines the range of
[static] (C++11) values generated by the engine.
(public static member constant)
constexpr size_t state_size the template parameter n. The engine state is n
[static] (C++11) values of UIntType
(public static member constant)
constexpr size_t shift_size the template parameter m
[static] (C++11) (public static member constant)
constexpr size_t mask_bits the template parameter r, also known as the twist
[static] (C++11) value.
(public static member constant)
constexpr UIntType xor_mask the template parameter a, the conditional xor-mask.
[static] (C++11) (public static member constant)
constexpr size_t tempering_u the template parameter u, first component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr UIntType tempering_d the template parameter d, second component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr size_t tempering_s the template parameter s, third component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr UIntType tempering_b the template parameter b, fourth component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr size_t tempering_t the template parameter t, fifth component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr UIntType tempering_c the template parameter c, sixth component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr size_t tempering_l the template parameter l, seventh component of the
[static] (C++11) bit-scrambling (tempering) matrix
(public static member constant)
constexpr UIntType the template parameter f
initialization_multiplier (public static member constant)
[static] (C++11)
constexpr UIntType default_seed the constant value 5489u
[static] (C++11) (public static member constant)

Notes¶

The Nth 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

// Run this code

#include <random>
#include <cassert>
int main()
{
std::mt19937 gen32;
std::mt19937_64 gen64;

for (auto n{1}; n != 10'000; gen32(), gen64(), ++n);

assert(gen32() == 4'123'659'995 and
gen64() == 9'981'545'732'273'789'042ULL);
}