std::mersenne_twister_engine

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 哋它亢++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 $\scriptsize {[0,2^w)}$ $[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 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 n$ th 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:

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.
Let y be $a \cdot (Y\ \mathsf{bitand}\ 1)$ $a\cdot(Y bitand 1)$ , and set $X_i$ $X i$ to $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:

Let $z_1$ $z 1$ be $X i xor ((X i rshift u) bitand d)$ .
Let $z_2$ $z 2$ be $X i xor (((X i lshift s) mod 2 w) bitand b)$ .
Let $z_3$ $z 3$ be $X i xor (((X i lshift t) mod 2 w) bitand c)$ .
Let $z_4$ $z 4$ be $z 3 xor (z 3 rshift l)$ .
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
`mt19937` (哋它亢++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` (哋它亢++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) (哋它亢++11)	constructs the engine (public member function)
seed (哋它亢++11)	sets the current state of the engine (public member function)
Generation
operator() (哋它亢++11)	advances the engine's state and returns the generated value (public member function)
discard (哋它亢++11)	advances the engine's state by a specified amount (public member function)
Characteristics
min [static] (哋它亢++11)	gets the smallest possible value in the output range (public static member function)
max [static] (哋它亢++11)	gets the largest possible value in the output range (public static member function)

Non-member functions

operator==operator!= (哋它亢++11)(哋它亢++11)(removed in 哋它亢++20)	compares the internal states of two pseudo-random number engines (function)
operator<<operator>> (哋它亢++11)	performs stream input and output on pseudo-random number engine (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);
}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (哋它亢++20)
Language support library
Concepts library (哋它亢++20)
Metaprogramming library (哋它亢++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (哋它亢++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (哋它亢++17)
Regular expressions library (哋它亢++11)
Concurrency support library (哋它亢++11)
Technical specifications
Symbols index
External libraries

Member functions
mersenne_twister_engine::mersenne_twister_engine (哋它亢++11)
mersenne_twister_engine::seed (哋它亢++11)
Generation
mersenne_twister_engine::operator() (哋它亢++11)
mersenne_twister_engine::discard (哋它亢++11)
Characteristics
mersenne_twister_engine::min (哋它亢++11)
mersenne_twister_engine::max (哋它亢++11)
Non-member functions
operator==operator!= (哋它亢++11)(哋它亢++11)(until 哋它亢++20)
operator<<operator>> (哋它亢++11)(哋它亢++11)

std::mersenne_twister_engine

Template parameters

Generator properties

Predefined specializations

Nested types

Data members

Member functions

Construction and Seeding

Generation

Characteristics

Non-member functions

Notes

Navigation