boost/random/shuffle_order.hpp

0001 /* boost random/shuffle_order.hpp header file
0002  *
0003  * Copyright Jens Maurer 2000-2001
0004  * Copyright Steven Watanabe 2010
0005  * Distributed under the Boost Software License, Version 1.0. (See
0006  * accompanying file LICENSE_1_0.txt or copy at
0007  * http://www.boost.org/LICENSE_1_0.txt)
0008  *
0009  * See http://www.boost.org for most recent version including documentation.
0010  *
0011  * $Id$
0012  *
0013  */
0014
0015 #ifndef BOOST_RANDOM_SHUFFLE_ORDER_HPP
0016 #define BOOST_RANDOM_SHUFFLE_ORDER_HPP
0017
0018 #include <iostream>
0019 #include <algorithm>     // std::copy
0020 #include <cassert>
0021 #include <boost/config.hpp>
0022 #include <boost/limits.hpp>
0023 #include <boost/static_assert.hpp>
0024 #include <boost/cstdint.hpp>
0025 #include <boost/random/detail/operators.hpp>
0026 #include <boost/random/detail/seed.hpp>
0027 #include <boost/random/detail/signed_unsigned_tools.hpp>
0028 #include <boost/random/linear_congruential.hpp>
0029
0030 #include <boost/random/detail/disable_warnings.hpp>
0031
0032 namespace boost {
0033 namespace random {
0034
0035 /**
0036  * Instatiations of class template @c shuffle_order_engine model a
0037  * \pseudo_random_number_generator. It mixes the output
0038  * of some (usually \linear_congruential_engine)
0039  * \uniform_random_number_generator to get better statistical properties.
0040  * The algorithm is described in
0041  *
0042  *  @blockquote
0043  *  "Improving a poor random number generator", Carter Bays
0044  *  and S.D. Durham, ACM Transactions on Mathematical Software,
0045  *  Vol 2, No. 1, March 1976, pp. 59-64.
0046  *  http://doi.acm.org/10.1145/355666.355670
0047  *  @endblockquote
0048  *
0049  * The output of the base generator is buffered in an array of
0050  * length k. Every output X(n) has a second role: It gives an
0051  * index into the array where X(n+1) will be retrieved. Used
0052  * array elements are replaced with fresh output from the base
0053  * generator.
0054  *
0055  * Template parameters are the base generator and the array
0056  * length k, which should be around 100.
0057  */
0058 template<class UniformRandomNumberGenerator, std::size_t k>
0059 class shuffle_order_engine
0060 {
0061 public:
0062     typedef UniformRandomNumberGenerator base_type;
0063     typedef typename base_type::result_type result_type;
0064
0065     BOOST_STATIC_CONSTANT(bool, has_fixed_range = false);
0066     BOOST_STATIC_CONSTANT(std::size_t, buffer_size = k);
0067     BOOST_STATIC_CONSTANT(std::size_t, table_size = k);
0068
0069     BOOST_STATIC_ASSERT(std::numeric_limits<result_type>::is_integer);
0070     BOOST_STATIC_ASSERT(k > 0);
0071
0072     /**
0073      * Constructs a @c shuffle_order_engine by invoking the
0074      * default constructor of the base generator.
0075      *
0076      * Complexity: Exactly k+1 invocations of the base generator.
0077      */
0078     shuffle_order_engine() : _rng() { init(); }
0079     /**
0080      * Constructs a @c shuffle_output_engine by invoking the one-argument
0081      * constructor of the base generator with the parameter seed.
0082      *
0083      * Complexity: Exactly k+1 invocations of the base generator.
0084      */
0085     BOOST_RANDOM_DETAIL_ARITHMETIC_CONSTRUCTOR(shuffle_order_engine,
0086                                                result_type, s)
0087     { _rng.seed(s); init(); }
0088     BOOST_RANDOM_DETAIL_SEED_SEQ_CONSTRUCTOR(shuffle_order_engine, SeedSeq, seq)
0089     { _rng.seed(seq); init(); }
0090     /**
0091      * Constructs a @c shuffle_output_engine by using a copy
0092      * of the provided generator.
0093      *
0094      * Precondition: The template argument UniformRandomNumberGenerator
0095      * shall denote a CopyConstructible type.
0096      *
0097      * Complexity: Exactly k+1 invocations of the base generator.
0098      */
0099     explicit shuffle_order_engine(const base_type & rng) : _rng(rng) { init(); }
0100
0101 #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES
0102     explicit shuffle_order_engine(base_type&& rng) : _rng(rng) { init(); }
0103 #endif
0104
0105     template<class It> shuffle_order_engine(It& first, It last)
0106       : _rng(first, last) { init(); }
0107     void seed() { _rng.seed(); init(); }
0108     /**
0109      * Invokes the one-argument seed method of the base generator
0110      * with the parameter seed and re-initializes the internal buffer array.
0111      *
0112      * Complexity: Exactly k+1 invocations of the base generator.
0113      */
0114     BOOST_RANDOM_DETAIL_ARITHMETIC_SEED(shuffle_order_engine,
0115         result_type, seed_arg)
0116     { _rng.seed(seed_arg); init(); }
0117     /**
0118      * Invokes the one-argument seed method of the base generator
0119      * with the parameter seq and re-initializes the internal buffer array.
0120      *
0121      * Complexity: Exactly k+1 invocations of the base generator.
0122      */
0123     BOOST_RANDOM_DETAIL_SEED_SEQ_SEED(shuffle_order_engine, SeedSeq, seq)
0124     { _rng.seed(seq); init(); }
0125     template<class It> void seed(It& first, It last)
0126     { _rng.seed(first, last); init(); }
0127
0128     const base_type& base() const { return _rng; }
0129
0130     result_type operator()() {
0131         // calculating the range every time may seem wasteful.  However, this
0132         // makes the information locally available for the optimizer.
0133         typedef typename boost::random::traits::make_unsigned<result_type>::type base_unsigned;
0134         const base_unsigned brange =
0135             detail::subtract<result_type>()((max)(), (min)());
0136         const base_unsigned off =
0137             detail::subtract<result_type>()(y, (min)());
0138
0139         base_unsigned j;
0140         if(k == 1) {
0141             j = 0;
0142         } else if(brange < (std::numeric_limits<base_unsigned>::max)() / k) {
0143             // try to do it in the native type if we know that it won't
0144             // overflow
0145             j = k * off / (brange + 1);
0146         } else if(brange < (std::numeric_limits<uintmax_t>::max)() / k) {
0147             // Otherwise try to use uint64_t
0148             j = static_cast<base_unsigned>(
0149                 static_cast<uintmax_t>(off) * k /
0150                 (static_cast<uintmax_t>(brange) + 1));
0151         } else {
0152             boost::uintmax_t divisor =
0153                 static_cast<boost::uintmax_t>(brange) + 1;
0154             j = static_cast<base_unsigned>(detail::muldiv(off, k, divisor));
0155         }
0156         // assert(0 <= j && j < k);
0157         y = v[j];
0158         v[j] = _rng();
0159         return y;
0160     }
0161
0162     /** Advances the generator by z steps. */
0163     void discard(boost::uintmax_t z)
0164     {
0165         for(boost::uintmax_t j = 0; j < z; ++j) {
0166             (*this)();
0167         }
0168     }
0169
0170     /** Fills a range with pseudo-random values. */
0171     template<class Iter>
0172     void generate(Iter first, Iter last)
0173     { detail::generate_from_int(*this, first, last); }
0174
0175     /** Returns the smallest value that the generator can produce. */
0176     static BOOST_CONSTEXPR result_type min BOOST_PREVENT_MACRO_SUBSTITUTION ()
0177     { return (base_type::min)(); }
0178     /** Returns the largest value that the generator can produce. */
0179     static BOOST_CONSTEXPR result_type max BOOST_PREVENT_MACRO_SUBSTITUTION ()
0180     { return (base_type::max)(); }
0181
0182     /** Writes a @c shuffle_order_engine to a @c std::ostream. */
0183     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, shuffle_order_engine, s)
0184     {
0185         os << s._rng;
0186         for(std::size_t i = 0; i < k; ++i)
0187             os << ' ' << s.v[i];
0188         os << ' ' << s.y;
0189         return os;
0190     }
0191
0192     /** Reads a @c shuffle_order_engine from a @c std::istream. */
0193     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, shuffle_order_engine, s)
0194     {
0195         is >> s._rng;
0196         for(std::size_t i = 0; i < k; ++i)
0197             is >> std::ws >> s.v[i];
0198         is >> std::ws >> s.y;
0199         return is;
0200     }
0201
0202     /** Returns true if the two generators will produce identical sequences. */
0203     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(shuffle_order_engine, x, y)
0204     { return x._rng == y._rng && x.y == y.y && std::equal(x.v, x.v+k, y.v); }
0205     /** Returns true if the two generators will produce different sequences. */
0206     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(shuffle_order_engine)
0207
0208 private:
0209
0210     /// \cond show_private
0211
0212     void init()
0213     {
0214         // we cannot use std::generate, because it uses pass-by-value for _rng
0215         for(result_type * p = v; p != v+k; ++p)
0216             *p = _rng();
0217         y = _rng();
0218     }
0219
0220     /// \endcond
0221
0222     base_type _rng;
0223     result_type v[k];
0224     result_type y;
0225 };
0226
0227 #ifndef BOOST_NO_INCLASS_MEMBER_INITIALIZATION
0228 //  A definition is required even for integral static constants
0229 template<class URNG, std::size_t k>
0230 const bool shuffle_order_engine<URNG, k>::has_fixed_range;
0231 template<class URNG, std::size_t k>
0232 const std::size_t shuffle_order_engine<URNG, k>::table_size;
0233 template<class URNG, std::size_t k>
0234 const std::size_t shuffle_order_engine<URNG, k>::buffer_size;
0235 #endif
0236
0237 /**
0238  * According to Harry Erwin (private e-mail), the specialization
0239  * @c kreutzer1986 was suggested in:
0240  *
0241  * @blockquote
0242  * "System Simulation: Programming Styles and Languages (International
0243  * Computer Science Series)", Wolfgang Kreutzer, Addison-Wesley, December 1986.
0244  * @endblockquote
0245  */
0246 typedef shuffle_order_engine<
0247     linear_congruential_engine<uint32_t, 1366, 150889, 714025>,
0248     97> kreutzer1986;
0249
0250 /**
0251  * The specialization @c knuth_b is specified by the C++ standard.
0252  * It is described in
0253  *
0254  * @blockquote
0255  * "The Art of Computer Programming, Second Edition, Volume 2,
0256  * Seminumerical Algorithms", Donald Knuth, Addison-Wesley, 1981.
0257  * @endblockquote
0258  */
0259 typedef shuffle_order_engine<minstd_rand0, 256> knuth_b;
0260
0261 } // namespace random
0262
0263 using random::kreutzer1986;
0264
0265 } // namespace boost
0266
0267 #include <boost/random/detail/enable_warnings.hpp>
0268
0269 #endif // BOOST_RANDOM_SHUFFLE_OUTPUT_HPP