29 Numerics library [numerics]

29.6 Random number generation [rand]

29.6.3 Random number engine class templates [rand.eng]

Each type instantiated from a class template specified in this section [rand.eng] satisfies the requirements of a random number engine type.

Except where specified otherwise, the complexity of each function specified in this section [rand.eng] is constant.

Except where specified otherwise, no function described in this section [rand.eng] throws an exception.

Every function described in this section [rand.eng] that has a function parameter q of type Sseq& for a template type parameter named Sseq that is different from type seed_­seq throws what and when the invocation of q.generate throws.

Descriptions are provided in this section [rand.eng] only for engine operations that are not described in [rand.req.eng] or for operations where there is additional semantic information. In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.

Each template specified in this section [rand.eng] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold. A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

For every random number engine and for every random number engine adaptor X defined in this subclause ([rand.eng]) and in subclause [rand.adapt]:

The extent to which an implementation determines that a type cannot be a seed sequence is unspecified, except that as a minimum a type shall not qualify as a seed sequence if it is implicitly convertible to X​::​result_­type.

29.6.3.1 Class template linear_­congruential_­engine [rand.eng.lcong]

A linear_­congruential_­engine random number engine produces unsigned integer random numbers. The state x of a linear_­congruential_­engine object x is of size 1 and consists of a single integer. The transition algorithm is a modular linear function of the form ; the generation algorithm is .

template<class UIntType, UIntType a, UIntType c, UIntType m>
  class linear_congruential_engine {
  public:
    // types
    using result_type = UIntType;

    // engine characteristics
    static constexpr result_type multiplier = a;
    static constexpr result_type increment = c;
    static constexpr result_type modulus = m;
    static constexpr result_type min() { return c == 0u ? 1u: 0u; }
    static constexpr result_type max() { return m - 1u; }
    static constexpr result_type default_seed = 1u;

    // constructors and seeding functions
    explicit linear_congruential_engine(result_type s = default_seed);
    template<class Sseq> explicit linear_congruential_engine(Sseq& q);
    void seed(result_type s = default_seed);
    template<class Sseq> void seed(Sseq& q);

    // generating functions
    result_type operator()();
    void discard(unsigned long long z);
  };

If the template parameter m is 0, the modulus m used throughout this section [rand.eng.lcong] is numeric_­limits<result_­type>​::​max() plus 1. [Note: m need not be representable as a value of type result_­type. end note]

If the template parameter m is not 0, the following relations shall hold: a < m and c < m.

The textual representation consists of the value of x.

explicit linear_congruential_engine(result_type s = default_seed);

Effects: Constructs a linear_­congruential_­engine object. If is 0 and is 0, sets the engine's state to 1, otherwise sets the engine's state to .

template<class Sseq> explicit linear_congruential_engine(Sseq& q);

Effects: Constructs a linear_­congruential_­engine object. With and a an array (or equivalent) of length , invokes q.generate(, ) and then computes . If is 0 and S is 0, sets the engine's state to 1, else sets the engine's state to S.

29.6.3.2 Class template mersenne_­twister_­engine [rand.eng.mers]

A mersenne_­twister_­engine random number engine270 produces unsigned integer random numbers in the closed interval . The state x of a mersenne_­twister_­engine object x is of size n and consists of a sequence X of n values of the type delivered by x; all subscripts applied to X are to be taken modulo n.

The transition algorithm employs a twisted generalized feedback shift register defined by shift values n and m, a twist value r, and a conditional xor-mask a. To improve the uniformity of the result, the bits of the raw shift register are additionally tempered (i.e., scrambled) according to a bit-scrambling matrix defined by values and .

The state transition is performed as follows:

  1. a)Concatenate the upper bits of with the lower r bits of to obtain an unsigned integer value Y.

  2. b)With , set to .

The sequence X is initialized with the help of an initialization multiplier f.

The generation algorithm determines the unsigned integer values as follows, then delivers as its result:

  1. a)Let .

  2. b)Let .

  3. c)Let .

  4. d)Let .

template<class UIntType, size_t w, size_t n, size_t m, size_t r,
         UIntType a, size_t u, UIntType d, size_t s,
         UIntType b, size_t t,
         UIntType c, size_t l, UIntType f>
  class mersenne_twister_engine {
  public:
    // types
    using result_type = UIntType;

    // engine characteristics
    static constexpr size_t word_size = w;
    static constexpr size_t state_size = n;
    static constexpr size_t shift_size = m;
    static constexpr size_t mask_bits = r;
    static constexpr UIntType xor_mask = a;
    static constexpr size_t tempering_u = u;
    static constexpr UIntType tempering_d = d;
    static constexpr size_t tempering_s = s;
    static constexpr UIntType tempering_b = b;
    static constexpr size_t tempering_t = t;
    static constexpr UIntType tempering_c = c;
    static constexpr size_t tempering_l = l;
    static constexpr UIntType initialization_multiplier = f;
    static constexpr result_type min() { return 0; }
    static constexpr result_type max() { return  ; }
    static constexpr result_type default_seed = 5489u;

    // constructors and seeding functions
    explicit mersenne_twister_engine(result_type value = default_seed);
    template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
    void seed(result_type value = default_seed);
    template<class Sseq> void seed(Sseq& q);

    // generating functions
    result_type operator()();
    void discard(unsigned long long z);
  };

The following relations shall hold: 0 < m, m <= n, 2u < w, r <= w, u <= w, s <= w, t <= w, l <= w, w <= numeric_­limits<UIntType>​::​digits, a <= (1u<<w) - 1u, b <= (1u<<w) - 1u, c <= (1u<<w) - 1u, d <= (1u<<w) - 1u, and f <= (1u<<w) - 1u.

The textual representation of x consists of the values of , in that order.

explicit mersenne_twister_engine(result_type value = default_seed);

Effects: Constructs a mersenne_­twister_­engine object. Sets to . Then, iteratively for , sets to

Complexity: .

template<class Sseq> explicit mersenne_twister_engine(Sseq& q);

Effects: Constructs a mersenne_­twister_­engine object. With and a an array (or equivalent) of length , invokes q.generate(, ) and then, iteratively for , sets to . Finally, if the most significant bits of are zero, and if each of the other resulting is 0, changes to .

The name of this engine refers, in part, to a property of its period: For properly-selected values of the parameters, the period is closely related to a large Mersenne prime number.

29.6.3.3 Class template subtract_­with_­carry_­engine [rand.eng.sub]

A subtract_­with_­carry_­engine random number engine produces unsigned integer random numbers.

The state x of a subtract_­with_­carry_­engine object x is of size , and consists of a sequence X of r integer values ; all subscripts applied to X are to be taken modulo r. The state x additionally consists of an integer c (known as the carry) whose value is either 0 or 1.

The state transition is performed as follows:

  1. a)Let .

  2. b)Set to . Set c to 1 if , otherwise set c to 0.

[Note: This algorithm corresponds to a modular linear function of the form , where b is of the form and . end note]

The generation algorithm is given by , where y is the value produced as a result of advancing the engine's state as described above.

template<class UIntType, size_t w, size_t s, size_t r>
  class subtract_with_carry_engine {
  public:
    // types
    using result_type = UIntType;

    // engine characteristics
    static constexpr size_t word_size = w;
    static constexpr size_t short_lag = s;
    static constexpr size_t long_lag = r;
    static constexpr result_type min() { return 0; }
    static constexpr result_type max() { return ; }
    static constexpr result_type default_seed = 19780503u;

    // constructors and seeding functions
    explicit subtract_with_carry_engine(result_type value = default_seed);
    template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
    void seed(result_type value = default_seed);
    template<class Sseq> void seed(Sseq& q);

    // generating functions
    result_type operator()();
    void discard(unsigned long long z);
  };

The following relations shall hold: 0u < s, s < r, 0 < w, and w <= numeric_­limits<UIntType>​::​digits.

The textual representation consists of the values of , in that order, followed by c.

explicit subtract_with_carry_engine(result_type value = default_seed);

Effects: Constructs a subtract_­with_­carry_­engine object. Sets the values of , in that order, as specified below. If is then 0, sets c to 1; otherwise sets c to 0.

To set the values , first construct e, a linear_­congruential_­engine object, as if by the following definition:

linear_congruential_engine<result_type,
                          40014u,0u,2147483563u> e(value == 0u ? default_seed : value);

Then, to set each , obtain new values from successive invocations of e taken modulo . Set to .

Complexity: Exactly invocations of e.

template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);

Effects: Constructs a subtract_­with_­carry_­engine object. With and a an array (or equivalent) of length , invokes q.generate(, ) and then, iteratively for , sets to . If is then 0, sets c to 1; otherwise sets c to 0.