| Home | Libraries | People | FAQ | More

## Class template additive_combine_engine

boost::random::additive_combine_engine

## Synopsis

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

    template<typename MLCG1, typename MLCG2>
    class additive_combine_engine {
    public:
      // types
      typedef MLCG1              first_base;
      typedef MLCG2              second_base;
      typedef MLCG1::result_type result_type;

      // construct/copy/destruct
      additive_combine_engine();
      explicit additive_combine_engine(result_type);
      template<typename SeedSeq> explicit additive_combine_engine(SeedSeq &);
      additive_combine_engine(typename MLCG1::result_type,
                              typename MLCG2::result_type);
      template<typename It> additive_combine_engine(It &, It);

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

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

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

      // public data members
      static const bool has_fixed_range;
    };

## Description

An instantiation of class template `additive_combine_engine` models a pseudo-random number generator . It combines two multiplicative linear_congruential_engine number generators, i.e. those with `c` = 0. It is described in

> "Efficient and Portable Combined Random Number Generators", Pierre L'Ecuyer, Communications of the ACM, Vol. 31, No. 6, June 1988, pp. 742-749, 774

The template parameters MLCG1 and MLCG2 shall denote two different linear_congruential_engine number generators, each with c = 0. Each invocation returns a random number X(n) := (MLCG1(n) - MLCG2(n)) mod (m1 - 1), where m1 denotes the modulus of MLCG1.

### `additive_combine_engine` public construct/copy/destruct

1.     additive_combine_engine();

   Constructs an ``additive_combine_engine`` using the default constructors of the two base generators.

2.     explicit additive_combine_engine(result_type seed);

   Constructs an ``additive_combine_engine``, using seed as the constructor argument for both base generators.

3.     template<typename SeedSeq> explicit additive_combine_engine(SeedSeq & seq);

   Constructs an ``additive_combine_engine``, using seq as the constructor argument for both base generators.

   | Warning
   The semantics of this function are liable to change. A ``seed_seq`` is designed to generate all the seeds in one shot, but this seeds the two base engines independantly and probably ends up giving the same sequence to both.

4.     additive_combine_engine(typename MLCG1::result_type seed1,
                               typename MLCG2::result_type seed2);

   Constructs an ``additive_combine_engine``, using `seed1` and `seed2` as the constructor argument to the first and second base generators, respectively.

5.     template<typename It> additive_combine_engine(It & first, It last);

   Contructs an ``additive_combine_engine`` with values from the range defined by the input iterators first and last. first will be modified to point to the element after the last one used.

   Throws: `std::invalid_argument` if the input range is too small.

   Exception Safety: Basic

### `additive_combine_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

### `additive_combine_engine` public member functions

1.     void seed();

   Seeds an ``additive_combine_engine`` using the default seeds of the two base generators.

2.     void seed(result_type seed);

   Seeds an ``additive_combine_engine``, using `seed` as the seed for both base generators.

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

   Seeds an ``additive_combine_engine``, using `seq` to seed both base generators.

   See the warning on the corresponding constructor.

4.     void seed(typename MLCG1::result_type seed1,
                 typename MLCG2::result_type seed2);

   Seeds an `additive_combine` generator, using `seed1` and `seed2` as the seeds to the first and second base generators, respectively.

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

   Seeds an ``additive_combine_engine`` with values from the range defined by the input iterators first and last. first will be modified to point to the element after the last one used.

   Throws: `std::invalid_argument` if the input range is too small.

   Exception Safety: Basic

6.     result_type operator()();

   Returns the next value of the generator.

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

   Fills a range with random values

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

   Advances the state of the generator by `z`.

### `additive_combine_engine` friend functions

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

   Writes the state of an ``additive_combine_engine`` to a `std::ostream`. The textual representation of an ``additive_combine_engine`` is the textual representation of the first base generator followed by the textual representation of the second base generator.

2.     template<typename CharT, typename Traits>
         friend std::basic_istream< CharT, Traits > &
         operator>>(std::basic_istream< CharT, Traits > & is,
                    const additive_combine_engine & r);

   Reads the state of an ``additive_combine_engine`` from a `std::istream`.

3.     friend bool operator==(const additive_combine_engine & x,
                              const additive_combine_engine & y);

   Returns: true iff the two `additive_combine_engines` will produce the same sequence of values.

4.     friend bool operator!=(const additive_combine_engine & lhs,
                              const additive_combine_engine & rhs);

   Returns: true iff the two `additive_combine_engines` will produce different sequences of values.