| Home | Libraries | People | FAQ | More

## Class template mersenne_twister_engine

boost::random::mersenne_twister_engine

## Synopsis

    // In header: <boost/random/mersenne_twister.hpp>

    template<typename 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 {
    public:
      // types
      typedef UIntType result_type;

      // construct/copy/destruct
      mersenne_twister_engine();
      explicit mersenne_twister_engine(UIntType);
      template<typename It> mersenne_twister_engine(It &, It);
      template<typename SeedSeq> explicit mersenne_twister_engine(SeedSeq &);

      // public member functions
      void seed();
      void seed(UIntType);
      template<typename SeeqSeq> void seed(SeeqSeq &);
      template<typename It> void seed(It &, It);
      result_type operator()();
      template<typename Iter> void generate(Iter, Iter);
      void discard(boost::uintmax_t);

      // public static functions
      static result_type min();
      static result_type max();

      // friend functions
      template<typename CharT, typename Traits>
        friend std::basic_ostream< CharT, Traits > &
        operator<<(std::basic_ostream< CharT, Traits > &,
                   const mersenne_twister_engine &);
      template<typename CharT, typename Traits>
        friend std::basic_istream< CharT, Traits > &
        operator>>(std::basic_istream< CharT, Traits > &,
                   mersenne_twister_engine &);
      friend bool operator==(const mersenne_twister_engine &,
                             const mersenne_twister_engine &);
      friend bool operator!=(const mersenne_twister_engine &,
                             const mersenne_twister_engine &);

      // public data members
      static const std::size_t word_size;
      static const std::size_t state_size;
      static const std::size_t shift_size;
      static const std::size_t mask_bits;
      static const UIntType xor_mask;
      static const std::size_t tempering_u;
      static const UIntType tempering_d;
      static const std::size_t tempering_s;
      static const UIntType tempering_b;
      static const std::size_t tempering_t;
      static const UIntType tempering_c;
      static const std::size_t tempering_l;
      static const UIntType initialization_multiplier;
      static const UIntType default_seed;
      static const UIntType parameter_a;
      static const std::size_t output_u;
      static const std::size_t output_s;
      static const UIntType output_b;
      static const std::size_t output_t;
      static const UIntType output_c;
      static const std::size_t output_l;
      static const bool has_fixed_range;
    };

## Description

Instantiations of class template mersenne_twister_engine model a pseudo-random number generator . It uses the algorithm described in

> "Mersenne Twister: A 623-dimensionally equidistributed uniform pseudo-random number generator", Makoto Matsumoto and Takuji Nishimura, ACM Transactions on Modeling and Computer Simulation: Special Issue on Uniform Random Number Generation, Vol. 8, No. 1, January 1998, pp. 3-30.

| Note
The boost variant has been implemented from scratch and does not derive from or use mt19937.c provided on the above WWW site. However, it was verified that both produce identical output.

The seeding from an integer was changed in April 2005 to address a weakness.

The quality of the generator crucially depends on the choice of the parameters. User code should employ one of the sensibly parameterized generators such as mt19937 instead.

The generator requires considerable amounts of memory for the storage of its state array. For example, mt11213b requires about 1408 bytes and mt19937 requires about 2496 bytes.

### `mersenne_twister_engine` public construct/copy/destruct

1.     mersenne_twister_engine();

   Constructs a ``mersenne_twister_engine`` and calls `seed()`.

2.     explicit mersenne_twister_engine(UIntType value);

   Constructs a ``mersenne_twister_engine`` and calls `seed(value)`.

3.     template<typename It> mersenne_twister_engine(It & first, It last);

4.     template<typename SeedSeq> explicit mersenne_twister_engine(SeedSeq & seq);

   Constructs a `mersenne_twister_engine` and calls `seed(gen)`.

   | Note
   The copy constructor will always be preferred over the templated constructor.

### `mersenne_twister_engine` public member functions

1.     void seed();

   Calls `seed(default_seed)`.

2.     void seed(UIntType value);

   Sets the state x(0) to v mod 2w. Then, iteratively, sets x(i) to (i + f * (x(i-1) xor (x(i-1) rshift w-2))) mod 2w for i = 1 .. n-1. x(n) is the first value to be returned by operator().

3.     template<typename SeeqSeq> void seed(SeeqSeq & seq);

   Seeds a `mersenne_twister_engine` using values produced by seq.generate().

4.     template<typename It> void seed(It & first, It last);

   Sets the state of the generator using values from an iterator range.

5.     result_type operator()();

   Produces the next value of the generator.

6.     template<typename Iter> void generate(Iter first, Iter last);

   Fills a range with random values

7.     void discard(boost::uintmax_t z);

   Advances the state of the generator by `z` steps. Equivalent to

       for(unsigned long long i = 0; i < z; ++i) {
           gen();
       }

### `mersenne_twister_engine` public static functions

1.     static result_type min();

   Returns the smallest value that the generator can produce.

2.     static result_type max();

   Returns the largest value that the generator can produce.

### `mersenne_twister_engine` friend functions

1.     template<typename CharT, typename Traits>
         friend std::basic_ostream< CharT, Traits > &
         operator<<(std::basic_ostream< CharT, Traits > & os,
                    const mersenne_twister_engine & mt);

   Writes a `mersenne_twister_engine` to a `std::ostream`

2.     template<typename CharT, typename Traits>
         friend std::basic_istream< CharT, Traits > &
         operator>>(std::basic_istream< CharT, Traits > & is,
                    mersenne_twister_engine & mt);

   Reads a `mersenne_twister_engine` from a `std::istream`

3.     friend bool operator==(const mersenne_twister_engine & x_,
                              const mersenne_twister_engine & y_);

   Returns true if the two generators are in the same state, and will thus produce identical sequences.

4.     friend bool operator!=(const mersenne_twister_engine & x_,
                              const mersenne_twister_engine & y_);

   Returns true if the two generators are in different states.