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