Namespaces
Variants
Views
Actions

std::mersenne_twister_engine

From cppreference.com
< cpp‎ | numeric‎ | random
 
 
 
 
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 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, 2w
)
.

Contents

[edit] 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 restriction is violated, the program is ill-formed:

  • m is in [1n].
  • The following expressions are all true:
  • Given (1u << w) - 1u as w1, the following expressions are all true:
  • a <= w1
  • b <= w1
  • c <= w1
  • d <= w1
  • f <= w1

[edit] 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:

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

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

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

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

[edit] 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[edit]

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[edit]

[edit] Nested types

Type Definition
result_type UIntType

[edit] 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)

[edit] Member functions

Construction and Seeding
constructs the engine
(public member function) [edit]
(C++11)
sets the current state of the engine
(public member function) [edit]
Generation
advances the engine's state and returns the generated value
(public member function) [edit]
(C++11)
advances the engine's state by a specified amount
(public member function) [edit]
Characteristics
[static] (C++11)
gets the smallest possible value in the output range
(public static member function) [edit]
[static] (C++11)
gets the largest possible value in the output range
(public static member function) [edit]

[edit] Non-member functions

(C++11)(C++11)(removed in C++20)
compares the internal states of two pseudo-random number engines
(function) [edit]
performs stream input and output on pseudo-random number engine
(function template) [edit]

[edit] 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

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

#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);
}