home | help 
std::mersen...ster_engine(3)   C++ Standard Libary  std::mersen...ster_engine(3)

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 val-
     ues 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)\)aA.(Y bitand 1), and set
     \(X_i\)X
	    i	to   \(X_{i+man}\   \mathsf{xor}\   (Y\   \mathsf{rshift}\   1)\
     \mathsf{xor}\ y\)X
	    i+man 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{bi-
     tand}\ 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  con-
     stant)
	constexpr size_t state_size		     n
	[static]				      (public static member con-
     stant)
	constexpr size_t shift_size		     m
	[static]				     (public static member  con-
     stant)
	constexpr size_t mask_bits		     r
	[static]				      (public static member con-
     stant)
	constexpr UIntType xor_mask		     a
	[static]				     (public static member  con-
     stant)
	constexpr size_t tempering_u		     u
	[static]				      (public static member con-
     stant)
	constexpr UIntType tempering_d		     d
	[static]				     (public static member  con-
     stant)
	constexpr size_t tempering_s		     s
	[static]				      (public static member con-
     stant)
	constexpr UIntType tempering_b		     b
	[static]				     (public static member  con-
     stant)
	constexpr size_t tempering_t		     t
	[static]				      (public static member con-
     stant)
	constexpr UIntType tempering_c		     c
	[static]				     (public static member  con-
     stant)
	constexpr size_t tempering_l		     l
	[static]				      (public static member con-
     stant)
	constexpr UIntType initialization_multiplier f
	[static]				     (public static member  con-
     stant)
	constexpr UIntType default_seed 	     5489u
	[static]				      (public static member con-
     stant)

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 re-
     quired 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  stan-
     dard (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);
      }

http://cppreference.com 	   2024.06.10	    std::mersen...ster_engine(3)
home | help