boost/random/additive_combine.hpp
/* boost random/additive_combine.hpp header file
*
* Copyright Jens Maurer 2000-2001
* Distributed under the Boost Software License, Version 1.0. (See
* accompanying file LICENSE_1_0.txt or copy at
* http://www.boost.org/LICENSE_1_0.txt)
*
* See http://www.boost.org for most recent version including documentation.
*
* $Id: additive_combine.hpp 71018 2011-04-05 21:27:52Z steven_watanabe $
*
* Revision history
* 2001-02-18 moved to individual header files
*/
#ifndef BOOST_RANDOM_ADDITIVE_COMBINE_HPP
#define BOOST_RANDOM_ADDITIVE_COMBINE_HPP
#include <istream>
#include <iosfwd>
#include <algorithm> // for std::min and std::max
#include <boost/config.hpp>
#include <boost/cstdint.hpp>
#include <boost/random/detail/config.hpp>
#include <boost/random/detail/operators.hpp>
#include <boost/random/detail/seed.hpp>
#include <boost/random/linear_congruential.hpp>
namespace boost {
namespace random {
/**
* An instantiation of class template @c additive_combine_engine models a
* \pseudo_random_number_generator. It combines two multiplicative
* \linear_congruential_engine number generators, i.e. those with @c c = 0.
* It is described in
*
* @blockquote
* "Efficient and Portable Combined Random Number Generators", Pierre L'Ecuyer,
* Communications of the ACM, Vol. 31, No. 6, June 1988, pp. 742-749, 774
* @endblockquote
*
* 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.
*/
template<class MLCG1, class MLCG2>
class additive_combine_engine
{
public:
typedef MLCG1 first_base;
typedef MLCG2 second_base;
typedef typename MLCG1::result_type result_type;
// Required by old Boost.Random concept
BOOST_STATIC_CONSTANT(bool, has_fixed_range = false);
/**
* Returns the smallest value that the generator can produce
*/
static result_type min BOOST_PREVENT_MACRO_SUBSTITUTION ()
{ return 1; }
/**
* Returns the largest value that the generator can produce
*/
static result_type max BOOST_PREVENT_MACRO_SUBSTITUTION ()
{ return MLCG1::modulus-1; }
/**
* Constructs an @c additive_combine_engine using the
* default constructors of the two base generators.
*/
additive_combine_engine() : _mlcg1(), _mlcg2() { }
/**
* Constructs an @c additive_combine_engine, using seed as
* the constructor argument for both base generators.
*/
BOOST_RANDOM_DETAIL_ARITHMETIC_CONSTRUCTOR(additive_combine_engine,
result_type, seed_arg)
{
_mlcg1.seed(seed_arg);
_mlcg2.seed(seed_arg);
}
/**
* Constructs an @c additive_combine_engine, using seq as
* the constructor argument for both base generators.
*
* @xmlwarning
* The semantics of this function are liable to change.
* A @c 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.
* @endxmlwarning
*/
BOOST_RANDOM_DETAIL_SEED_SEQ_CONSTRUCTOR(additive_combine_engine,
SeedSeq, seq)
{
_mlcg1.seed(seq);
_mlcg2.seed(seq);
}
/**
* Constructs an @c additive_combine_engine, using
* @c seed1 and @c seed2 as the constructor argument to
* the first and second base generators, respectively.
*/
additive_combine_engine(typename MLCG1::result_type seed1,
typename MLCG2::result_type seed2)
: _mlcg1(seed1), _mlcg2(seed2) { }
/**
* Contructs an @c 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: @c std::invalid_argument if the input range is too small.
*
* Exception Safety: Basic
*/
template<class It> additive_combine_engine(It& first, It last)
: _mlcg1(first, last), _mlcg2(first, last) { }
/**
* Seeds an @c additive_combine_engine using the default
* seeds of the two base generators.
*/
void seed()
{
_mlcg1.seed();
_mlcg2.seed();
}
/**
* Seeds an @c additive_combine_engine, using @c seed as the
* seed for both base generators.
*/
BOOST_RANDOM_DETAIL_ARITHMETIC_SEED(additive_combine_engine,
result_type, seed_arg)
{
_mlcg1.seed(seed_arg);
_mlcg2.seed(seed_arg);
}
/**
* Seeds an @c additive_combine_engine, using @c seq to
* seed both base generators.
*
* See the warning on the corresponding constructor.
*/
BOOST_RANDOM_DETAIL_SEED_SEQ_SEED(additive_combine_engine,
SeedSeq, seq)
{
_mlcg1.seed(seq);
_mlcg2.seed(seq);
}
/**
* Seeds an @c additive_combine generator, using @c seed1 and @c seed2 as
* the seeds to the first and second base generators, respectively.
*/
void seed(typename MLCG1::result_type seed1,
typename MLCG2::result_type seed2)
{
_mlcg1.seed(seed1);
_mlcg2.seed(seed2);
}
/**
* Seeds an @c 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: @c std::invalid_argument if the input range is too small.
*
* Exception Safety: Basic
*/
template<class It> void seed(It& first, It last)
{
_mlcg1.seed(first, last);
_mlcg2.seed(first, last);
}
/** Returns the next value of the generator. */
result_type operator()() {
result_type val1 = _mlcg1();
result_type val2 = _mlcg2();
if(val2 < val1) return val1 - val2;
else return val1 - val2 + MLCG1::modulus - 1;
}
/** Fills a range with random values */
template<class Iter>
void generate(Iter first, Iter last)
{ detail::generate_from_int(*this, first, last); }
/** Advances the state of the generator by @c z. */
void discard(boost::uintmax_t z)
{
_mlcg1.discard(z);
_mlcg2.discard(z);
}
/**
* Writes the state of an @c additive_combine_engine to a @c
* std::ostream. The textual representation of an @c
* additive_combine_engine is the textual representation of
* the first base generator followed by the textual representation
* of the second base generator.
*/
BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, additive_combine_engine, r)
{ os << r._mlcg1 << ' ' << r._mlcg2; return os; }
/**
* Reads the state of an @c additive_combine_engine from a
* @c std::istream.
*/
BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, additive_combine_engine, r)
{ is >> r._mlcg1 >> std::ws >> r._mlcg2; return is; }
/**
* Returns: true iff the two @c additive_combine_engines will
* produce the same sequence of values.
*/
BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(additive_combine_engine, x, y)
{ return x._mlcg1 == y._mlcg1 && x._mlcg2 == y._mlcg2; }
/**
* Returns: true iff the two @c additive_combine_engines will
* produce different sequences of values.
*/
BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(additive_combine_engine)
private:
MLCG1 _mlcg1;
MLCG2 _mlcg2;
};
#ifndef BOOST_NO_INCLASS_MEMBER_INITIALIZATION
template<class MLCG1, class MLCG2>
const bool additive_combine_engine<MLCG1, MLCG2>::has_fixed_range;
#endif
/// \cond show_deprecated
/** Provided for backwards compatibility. */
template<class MLCG1, class MLCG2, typename MLCG1::result_type val = 0>
class additive_combine : public additive_combine_engine<MLCG1, MLCG2>
{
typedef additive_combine_engine<MLCG1, MLCG2> base_t;
public:
typedef typename base_t::result_type result_type;
additive_combine() {}
template<class T>
additive_combine(T& arg) : base_t(arg) {}
template<class T>
additive_combine(const T& arg) : base_t(arg) {}
template<class It>
additive_combine(It& first, It last) : base_t(first, last) {}
};
/// \endcond
/**
* The specialization \ecuyer1988 was suggested in
*
* @blockquote
* "Efficient and Portable Combined Random Number Generators", Pierre L'Ecuyer,
* Communications of the ACM, Vol. 31, No. 6, June 1988, pp. 742-749, 774
* @endblockquote
*/
typedef additive_combine_engine<
linear_congruential_engine<uint32_t, 40014, 0, 2147483563>,
linear_congruential_engine<uint32_t, 40692, 0, 2147483399>
> ecuyer1988;
} // namespace random
using random::ecuyer1988;
} // namespace boost
#endif // BOOST_RANDOM_ADDITIVE_COMBINE_HPP