|
+ Home | +Libraries | +People | +FAQ | +More | +
You should read the concepts documentation +before moving on.
+For a quick start, it may be sufficient to have a look at random_demo.cpp. +
+
| Header | +Contents | +
<boost/random.hpp>
+ documentation for generators |
+ Pseudo-random number generators (linear congruential, inversive + congruential, and others), distribution functions (uniform, normal, + exponential, and others) and miscellaneous decorator classes such as random_number_generator + for use in simulations, games, and testing. | +
<boost/nondet_random.hpp>
+ |
+ Non-deterministic random number generators. | +
An extensive test suite for the pseudo-random number generators and +distributions is available as random_test.cpp.
+Additional test programs include statistic_test.cpp +and histogram.cpp.
+Rationale
+The methods for generating and evaluating deterministic and non-deterministic +random numbers differ radically. Furthermore, due to the inherent deterministic +design of present-day computers, it is often difficult to implement +non-deterministic random number generation facilities. Thus, the random number +library is split into separate header files, mirroring the two different +application domains. +Header
+<boost/nondet_random.hpp><boost/nondet_random.hpp>
+Synopsis
+namespace boost {
+ class random_device;
+} // namespace boost
+
+
+
+random_device
+class random_device : noncopyable
+{
+public:
+ typedef unsigned int result_type;
+ static const bool has_fixed_range = true;
+ static const result_type min_value = /* implementation defined */;
+ static const result_type max_value = /* implementation defined */;
+ explicit random_device(const std::string& token = default_token);
+ ~random_device();
+ unsigned int operator()();
+};
+
+
+random_device models a
+non-deterministic random number
+generator.
+It uses one or more implementation-defined stochastic processes to
+generate a sequence of uniformly distributed non-deterministic random
+numbers. For those environments where a non-deterministic random
+number generator is not available, class random_device
+must not be implemented. See
++"Randomness Recommendations for Security", D. Eastlake, S. +Crocker, J. Schiller, Network Working Group, RFC1750, December 1994 ++for further discussions. + +
+Note: Some operating systems abstract the computer hardware +enough to make it difficult to non-intrusively monitor stochastic +processes. However, several do provide a special device for exactly +this purpose. It seems to be impossible to emulate the functionality +using Standard C++ only, so users should be aware that this class may +not be available on all platforms. + +
explicit random_device(const std::string& token = default_token)+ +Effects: Constructs a
random_device,
+optionally using the given token as an access
+specification (for example, a URL) to some implementation-defined
+service for monitoring a stochastic process.
+
+token is interpreted as a
+filesystem path. It is assumed that this path denotes an operating
+system pseudo-device which generates a stream of non-deterministic
+random numbers. The pseudo-device should never signal an error or
+end-of-file. Otherwise, std::ios_base::failure is
+thrown. By default, random_device uses the
+/dev/urandom pseudo-device to retrieve the random
+numbers. Another option would be to specify the
+/dev/random pseudo-device, which blocks on reads if the
+entropy pool has no more random bits available.
+
+
++
| class | time per invocation [usec] |
|---|---|
| random_device | 92.0 |
+The measurement error is estimated at +/- 1 usec. + +
+
+"Numerical Recipes in C: The art of scientific computing", William +H. Press, Saul A. Teukolsky, William A. Vetterling, Brian P. Flannery, +2nd ed., 1992, pp. 274-328 ++ +Depending on the requirements of the problem domain, different +variations of random number generators are appropriate: + +
+ +The goals for this library are the following: +
operator() returns a number.
+
+
+In the following table, X denotes a number generator
+class returning objects of type T, and u is
+a value of X.
+
++ +
NumberGenerator
+requirements | ||
|---|---|---|
| expression | return type | +pre/post-condition |
X::result_type | T | +std::numeric_limits<T>::is_specialized is true,
+T is LessThanComparable |
u.operator()() | T | - |
+ +Note: The NumberGenerator requirements do not impose any +restrictions on the characteristics of the returned numbers. + + +
+The tight lower bound of some (finite) set S is the (unique) +member l in S, so that for all v in S, l <= v holds. Likewise, the +tight upper bound of some (finite) set S is the (unique) +member u in S, so that for all v in S, v <= u holds. + +
+In the following table, X denotes a number generator
+class returning objects of type T, and v is
+a const value of X.
+
+
+ +
UniformRandomNumberGenerator
+requirements | ||
|---|---|---|
| expression | return type | +pre/post-condition |
X::has_fixed_range | bool |
+compile-time constant; if true, the range on which
+the random numbers are uniformly distributed is known at compile-time
+and members min_value and max_value
+exist. Note: This flag may also be false due to
+compiler limitations. |
X::min_value | T |
+compile-time constant; min_value is equal to
+v.min() |
X::max_value | T |
+compile-time constant; max_value is equal to
+v.max() |
v.min() | T |
+tight lower bound on the set of all values returned by
+operator(). The return value of this function shall not
+change during the lifetime of the object. |
v.max() | T |
+if std::numeric_limits<T>::is_integer, tight
+upper bound on the set of all values returned by
+operator(), otherwise, the smallest representable number
+larger than the tight upper bound on the set of all values returned by
+operator(). In any case, the return value of this
+function shall not change during the lifetime of the
+object. |
+The member functions min, max, and
+operator() shall have amortized constant time complexity.
+
+
+Note: For integer generators (i.e. integer T),
+the generated values x fulfill min() <= x <=
+max(), for non-integer generators (i.e. non-integer
+T), the generated values x fulfill
+min() <= x < max().
+
+Rationale: The range description with min and
+max serves two purposes. First, it allows scaling of the
+values to some canonical range, such as [0..1). Second, it describes
+the significant bits of the values, which may be relevant for further
+processing.
+
+The range is a closed interval [min,max] for integers, because the
+underlying type may not be able to represent the half-open interval
+[min,max+1). It is a half-open interval [min, max) for non-integers,
+because this is much more practical for borderline cases of continuous
+distributions.
+
+
+Note: The UniformRandomNumberGenerator concept does not
+require operator()(long) and thus it does not fulfill the
+RandomNumberGenerator (std:25.2.11 [lib.alg.random.shuffle])
+requirements. Use the
+random_number_generator
+adapter for that.
+
+
+Rationale: operator()(long) is not provided,
+because mapping the output of some generator with integer range to a
+different integer range is not trivial.
+
+
+
+
+The class
+random_device
+is a model for a non-deterministic random number generator.
+
+
+ +Note: This type of random-number generator is useful for +security applications, where it is important to prevent that an +outside attacker guesses the numbers and thus obtains your +encryption or authentication key. Thus, models of this concept should +be cautious not to leak any information, to the extent possible by the +environment. For example, it might be advisable to explicitly clear +any temporary storage as soon as it is no longer needed. + + +
+ +Donald E. Knuth gives an extensive overview on pseudo-random number +generation in his book "The Art of Computer Programming, Vol. 2, 3rd +edition, Addison-Wesley, 1997". The descriptions for the specific +generators contain additional references. +
+ +Note: Because the state of a pseudo-random number generator +is necessarily finite, the sequence of numbers returned by the +generator will loop eventually. + +
+In addition to the UniformRandomNumberGenerator requirements, a
+pseudo-random number generator has some additional requirements. In
+the following table, X denotes a pseudo-random number
+generator class returning objects of type T,
+x is a value of T, u is a value
+of X, and v is a const value of
+X.
+
+
+ +
PseudoRandomNumberGenerator
+requirements | ||
|---|---|---|
| expression | return type | +pre/post-condition |
X() | - | +creates a generator in some implementation-defined +state. Note: Several generators thusly created may possibly +produce dependent or identical sequences of random numbers. |
explicit X(...) | - | +creates a generator with user-provided state; the implementation +shall specify the the constructor argument(s) |
u.seed(...) | void | +sets the current state according to the argument(s); at least +functions with the same signature as the non-default +constructor(s) shall be provided. + |
v.validation(x) | bool |
+compares the pre-computed and hardcoded 10001th element in the
+generator's random number sequence with x. The generator
+must have been constructed by its default constructor and
+seed must not have been called for the validation to
+be meaningful.
+ |
+
+Note: The seed member function is similar to the
+assign member function in STL containers. However, the
+naming did not seem appropriate.
+
+
+
+Classes which model a pseudo-random number generator shall also model
+EqualityComparable, i.e. implement operator==. Two
+pseudo-random number generators are defined to be equivalent
+if they both return an identical sequence of numbers starting from a
+given state.
+
+Classes which model a pseudo-random number generator should also model
+the Streamable concept, i.e. implement operator<<
+and operator>>. If so,
+operator<< writes all current state of the
+pseudo-random number generator to the given ostream so
+that operator>> can restore the state at a later
+time. The state shall be written in a platform-independent manner,
+but it is assumed that the locales used for writing and
+reading be the same.
+
+The pseudo-random number generator with the restored state and the
+original at the just-written state shall be equivalent.
+
+
+Classes which model a pseudo-random number generator may also model
+the CopyConstructible and Assignable concepts. However, note that the
+sequences of the original and the copy are strongly correlated (in
+fact, they are identical), which may make them unsuitable for some
+problem domains. Thus, copying pseudo-random number generators is
+discouraged; they should always be passed by (non-const)
+reference.
+
+
+
+The classes
+rand48,
+minstd_rand,
+and
+mt19937
+are models for a pseudo-random number generator.
+
+
+Note: This type of random-number generator is useful for
+numerics, games and testing. The none-zero arguments constructor(s)
+and the seed() member function(s) allow for a
+user-provided state to be installed in the generator. This is useful
+for debugging Monte-Carlo algorithms and analyzing particular test
+scenarios. The Streamable concept allows to save/restore the state of
+the generator, for example to re-run a test suite at a later time.
+
+
+
+ +Note: Quasi-random number generators are useful for +Monte-Carlo integrations where specially crafted sequences of random +numbers will make the approximation converge faster. + +
+ +[Does anyone have a model?] + +
+
uniform_smallint
+uniform_int
+uniform_01
+uniform_real
+bernoulli_distribution
+geometric_distribution
+triangle_distribution
+exponential_distribution
+normal_distribution
+lognormal_distribution
+uniform_on_sphere
++Usually, there are several possible implementations of any given +mapping. Often, there is a choice between using more space, more +invocations of the underlying source of random numbers, or more +time-consuming arithmetic such as trigonometric functions. This +interface description does not mandate any specific implementation. +However, implementations which cannot reach certain values of the +specified distribution or otherwise do not converge statistically to +it are not acceptable. + +
+
| distribution | explanation | example |
|---|---|---|
uniform_smallint |
+discrete uniform distribution on a small set of integers (much +smaller than the range of the underlying generator) | +drawing from an urn | +
uniform_int |
+discrete uniform distribution on a set of integers; the underlying +generator may be called several times to gather enough randomness for +the output | +drawing from an urn | +
uniform_01 |
+continuous uniform distribution on the range [0,1); important +basis for other distributions | +- | +
uniform_real |
+continuous uniform distribution on some range [min, max) of real +numbers | +for the range [0, 2pi): randomly dropping a stick and measuring +its angle in radiants (assuming the angle is uniformly +distributed) | +
bernoulli_distribution |
+Bernoulli experiment: discrete boolean valued distribution with +configurable probability | +tossing a coin (p=0.5) | +
geometric_distribution |
+measures distance between outcomes of repeated Bernoulli experiments | +throwing a die several times and counting the number of tries +until a "6" appears for the first time | +
triangle_distribution |
+? | +? | +
exponential_distribution |
+exponential distribution | +measuring the inter-arrival time of alpha particles emitted by +radioactive matter | +
normal_distribution |
+counts outcomes of (infinitely) repeated Bernoulli experiments | +tossing a coin 10000 times and counting how many front sides are shown | +
lognormal_distribution |
+lognormal distribution (sometimes used in simulations) | +measuring the job completion time of an assembly line worker | +
uniform_on_sphere |
+uniform distribution on a unit sphere of arbitrary dimension | +choosing a random point on Earth (assumed to be a sphere) where to +spend the next vacations | +
+ +The template parameters of the distribution functions are always in +the order +
+All distribution functions satisfy the input iterator requirements
+(std:24.1.1 [lib.input.iterators]) in addition to the NumberGenerator
+requirements. After an invocation of operator(), the
+effects of invocations of operator* are undefined until
+the next call to operator++.
+
+
+In this description, I have refrained from documenting those members +in detail which are already defined in the +concept documentation. + + +
<boost/random.hpp>
+namespace boost {
+ template<class UniformRandomNumberGenerator, class IntType = int>
+ class uniform_smallint;
+ template<class UniformRandomNumberGenerator, class IntType = int>
+ class uniform_int;
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class uniform_01;
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class uniform_real;
+
+ // discrete distributions
+ template<class UniformRandomNumberGenerator>
+ class bernoulli_distribution;
+ template<class UniformRandomNumberGenerator, class IntType = int>
+ class geometric_distribution;
+
+ // continuous distributions
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class triangle_distribution;
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class exponential_distribution;
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class normal_distribution;
+ template<class UniformRandomNumberGenerator, class RealType = double>
+ class lognormal_distribution;
+ template<class UniformRandomNumberGenerator, class RealType = double,
+ class Cont = std::vector<RealType> >
+ class uniform_on_sphere;
+}
+
+
+uniform_smallint
+template<class UniformRandomNumberGenerator, class IntType = int>
+class uniform_smallint
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef IntType result_type;
+ static const bool has_fixed_range = false;
+ uniform_smallint(base_type & rng, IntType min, IntType max);
+ result_type operator()();
+ result_type min() const;
+ result_type max() const;
+};
+
+
+uniform_smallint models a
+uniform random number
+generator. On each invocation, it returns a random integer value
+uniformly distributed in the set of integer numbers {min, min+1,
+min+2, ..., max}. It assumes that the desired range (max-min+1) is
+small compared to the range of the underlying source of random
+numbers and thus makes no attempt to limit quantization errors.
+
+Let rout=(max-min+1) the desired range of integer numbers,
+and let rbase be the range of the underlying source of
+random numbers. Then, for the uniform distribution, the theoretical
+probability for any number i in the range rout will be
+pout(i) = 1/rout. Likewise, assume a uniform
+distribution on rbase for the underlying source of random
+numbers, i.e. pbase(i) = 1/rbase. Let
+pout_s(i) denote the random distribution generated by
+uniform_smallint. Then the sum over all i in
+rout of (pout_s(i)/pout(i)
+-1)2 shall not exceed
+rout/rbase2 (rbase mod
+rout)(rout - rbase mod
+rout).
+
+
+The template parameter UniformRandomNumberGenerator shall
+denote a class which models a uniform random number generator.
+Additionally, UniformRandomNumberGenerator::result_type
+shall denote an integral type. The template parameter
+IntType shall denote an integer-like value type.
+
+
+Note: The property above is the square sum of the relative +differences in probabilities between the desired uniform distribution +pout(i) and the generated distribution +pout_s(i). The property can be fulfilled with the +calculation (base_rng mod rout), as follows: Let r = +rbase mod rout. The base distribution on +rbase is folded onto the range rout. The +numbers i < r have assigned (rbase div +rout)+1 numbers of the base distribution, the rest has only +(rbase div rout). Therefore, +pout_s(i) = ((rbase div rout)+1) / +rbase for i < r and pout_s(i) = +(rbase div rout)/rbase otherwise. +Substituting this in the above sum formula leads to the desired +result. +
+Note: The upper bound for (rbase mod rout)(rout - rbase +mod rout) is rout2/4. Regarding the upper bound for the square +sum of the relative quantization error of rout3/(4*rbase2), it +seems wise to either choose rbase so that rbase > 10*rout2 or +ensure that rbase is divisible by rout. + + +
uniform_smallint(base_type & rng, IntType min, IntType max)+ +Effects: Constructs a
uniform_smallint
+functor with the uniform random number generator rng as
+the underlying source of random numbers. min and
+max are the lower and upper bounds of the output range,
+respectively.
+
+
+uniform_int
+template<class UniformRandomNumberGenerator, class IntType = int>
+class uniform_int
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef IntType result_type;
+ static const bool has_fixed_range = false;
+ uniform_int(base_type & rng, IntType min, IntType max);
+ IntType operator()();
+ result_type min() const;
+ result_type max() const;
+};
+
+
+uniform_int models a
+uniform random number
+generator. On each invocation, it returns a random integer
+value uniformly distributed in the set of integer numbers
+{min, min+1, min+2, ..., max}.
+
+
+The template parameter IntType shall denote an
+integer-like value type.
+
+
uniform_int(base_type & rng, IntType min, IntType max)+ +Effects: Constructs a
uniform_int functor
+with the uniform random number generator rng as the
+underlying source of random numbers. min and
+max are the lower and upper bounds of the output range,
+respectively.
+
+
+Note: Invocations of operator() may call the
+underlying generator several times and concatenate the result to build
+the required range. Thus, using this distribution with generators
+such as linear congruential ones which tend to produce non-random bits
+in some positions is strongly discouraged.
+
+
uniform_01
+template<class UniformRandomNumberGenerator, class RealType = double>
+class uniform_01
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ static const bool has_fixed_range = false;
+ explicit uniform_01(base_type & rng);
+ result_type operator()();
+ result_type min() const;
+ result_type max() const;
+};
+
+
+uniform_01 models a
+uniform random number
+generator. On each invocation, it returns a random floating-point
+value uniformly distributed in the range [0..1).
+
+The value is computed using
+std::numeric_limits<RealType>::digits random binary
+digits, i.e. the mantissa of the floating-point value is completely
+filled with random bits. [Note: Should this be configurable?]
+
+
+The template parameter RealType shall denote a float-like
+value type with support for binary operators +, -, and /. It must be
+large enough to hold floating-point numbers of value
+rng.max()-rng.min()+1.
+
+base_type::result_type must be a number-like value type,
+it must support static_cast<> to
+RealType and binary operator -.
+
+
+
+Note: The current implementation is buggy, because it may not
+fill all of the mantissa with random bits. I'm unsure how to fill a
+(to-be-invented) boost::bigfloat class with random bits
+efficiently. It's probably time for a traits class.
+
+
explicit uniform_01(base_type & rng)+ +Effects: Constructs a
uniform_01 functor
+with the given uniform random number generator as the underlying
+source of random numbers.
+
+
+uniform_real
+template<class UniformRandomNumberGenerator, class RealType = double>
+class uniform_real
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ static const bool has_fixed_range = false;
+ uniform_real(base_type & rng, RealType min, RealType max);
+ result_type operator()();
+ result_type min() const;
+ result_type max() const;
+};
+
+
+uniform_real models a
+uniform random number
+generator. On each invocation, it returns a random floating-point
+value uniformly distributed in the range [min..max). The value is
+computed using
+std::numeric_limits<RealType>::digits random binary
+digits, i.e. the mantissa of the floating-point value is completely
+filled with random bits.
++ +Note: The current implementation is buggy, because it may not +fill all of the mantissa with random bits. + + +
explicit uniform_real(base_type & rng, RealType min, RealType max)+ +Effects: Constructs a
uniform_real
+functor. rng specifies the uniform random number
+generator to be used as the underlying source of random numbers,
+min and max are the lower and upper bounds of
+the output range.
+
+
+bernoulli_distribution
+template<class UniformRandomNumberGenerator>
+class bernoulli_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef bool result_type;
+ bernoulli_distribution(base_type & rng, double q);
+ result_type operator()();
+};
+
+
+bernoulli_distribution
+model a number
+generator. It transforms a uniform distribution into a Bernoulli
+one.
+
+bernoulli_distribution(base_type & rng, double q)+ +Effects: Constructs a +
bernoulli_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. q is the parameter for the distribution.
+
+result_type operator()()+Returns: A random boolean value with p(true) = q and +p(false) = 1-q. For example, with q = 1/2 this can be interpreted as +tossing a coin. + + +
geometric_distribution
+template<class UniformRandomNumberGenerator, class IntType = int>
+class geometric_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef IntType result_type;
+ geometric_distribution(base_type& rng, double q);
+ result_type operator()();
+};
+
+
+
+geometric_distribution
+model a number
+generator. It transforms a uniform distribution into a geometric
+one.
+
+
+geometric_distribution(base_type& rng, const result_type& q)+ +Effects: Constructs a +
geometric_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. q is the parameter for the distribution.
++ +
result_type operator()()+ +Returns: A random integer value i >= 1 with +p(i) = (1-q) * qi-1. For example, with q = 5/6 this can be +interpreted as the number of times one has to roll a die until a given +number shows up. + + +
triangle_distribution
+template<class UniformRandomNumberGenerator, class RealType = double>
+class triangle_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ triangle_distribution(base_type& rng, result_type a, result_type b, result_type c);
+ result_type operator()();
+};
+
+
+
+triangle_distribution
+model a number
+generator. It transforms a uniform distribution into a triangle
+one.
+
+
+triangle_distribution(base_type& rng, result_type a, result_type b, result_type c)+ +Effects: Constructs a +
triangle_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. a, b, c are the parameters for the distribution.
++ +
result_type operator()()+ +Returns: A random floating-point value
x
+where a <= x <= c; x has a triangle
+distribution, where b is the most probable value for
+x.
+
+
+exponential_distribution
+template<class UniformRandomNumberGenerator, class RealType = double>
+class exponential_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ exponential_distribution(base_type& rng, const result_type& lambda);
+ result_type operator()();
+};
+
+
+exponential_distribution
+model a number
+generator. It transforms a uniform distribution into an
+exponential one.
+
+exponential_distribution(base_type& rng, const result_type& lambda)+ +Effects: Constructs an +
exponential_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. lambda is the parameter for the distribution.
++ +
result_type operator()()+ +Returns: A random floating-point value x +> 0 with p(x) =
lambda * exp(-lambda *
+x).
+
+
+normal_distribution
+template<class UniformRandomNumberGenerator, class RealType = double>
+class normal_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ explicit normal_distribution(base_type& rng, const result_type& mean = 0,
+ const result_type& sigma = 1);
+ result_type operator()();
+};
+
+
+normal_distribution
+model a number
+generator. It transforms a uniform distribution into a
+normal (Gaussian) one.
+
+normal_distribution(base_type& rng, const result_type& mean = 0, + const result_type& sigma = 1)+ +Effects: Constructs a +
normal_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. mean and sigma are the parameters for
+the distribution.
++ +
result_type operator()()+ +Returns: A random floating-point value x +with p(x) = 1/sqrt(2*pi*sigma) * exp(- (x-mean)2 / +(2*sigma2) ). + + +
lognormal_distribution
+template<class UniformRandomNumberGenerator, class RealType = double>
+class lognormal_distribution
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef RealType result_type;
+ explicit lognormal_distribution(base_type& rng, const result_type& mean,
+ const result_type& sigma);
+ result_type operator()();
+};
+
+
+lognormal_distribution
+model a number
+generator. It transforms a uniform distribution into a
+lognormal one.
+
+lognormal_distribution(base_type& rng, const result_type& mean = 0, + const result_type& sigma = 1)+ +Effects: Constructs a +
normal_distribution functor with the uniform random
+number generator rng as the underlying source of random
+numbers. mean and sigma are the parameters for
+the distribution.
++ +
result_type operator()()+ +Returns: A random floating-point value x +with p(x) = 1/(x * sigma * sqrt(2*pi*sigma)) * exp(- +(log(x)-mean)2 / (2*sigma2) ) for x > 0. + + +
uniform_on_sphere
+template<class UniformRandomNumberGenerator, class RealType = double,
+ class Cont = std::vector<RealType> >
+class uniform_on_sphere
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef Cont result_type;
+ explicit uniform_on_sphere(base_type & rng, int dim = 2);
+ const result_type & operator()();
+};
+
+
+uniform_on_sphere model a
+Generator (std:25.2.6 [lib.alg.generate]). It transforms a uniform
+distribution into a uniform distribution on the unit sphere of
+arbitrary dimension. The Cont template parameter must be
+a STL-like container type with begin and end
+operations returning non-const ForwardIterators of type
+Cont::iterator.
+
+explicit uniform_on_sphere(base_type & rng, int dim = 2)+ +Effects: Constructs a
uniform_on_sphere
+functor with the uniform random number generator rng as
+the underlying source of random numbers. dim is the
+dimension of the sphere.
++ +
result_type operator()()+ +Returns: A position on the unit sphere of +
dim dimensions in cartesian coordinates. The positions
+are uniformly distributed on the unit sphere.
++Complexity: Proportional to the number of dimensions. + +
+
detail::const_mod
+detail::linear_congruential
+rand48
+detail::additive_combined
+detail::shuffle_output
+detail::inversive_congruential
+detail::mersenne_twister
+detail. Any particular choice of parameters
+is represented as the appropriately specializing typedef
+in namespace boost.
+
++ +The following table gives an overview of some characteristics of the +generators. The cycle length is a rough estimate of the quality of +the generator; the approximate relative speed is a performance +measure, higher numbers mean faster random number generation. + +
+
| generator | length of cycle | memory +requirements | approximate relative speed | comment |
|---|---|---|---|---|
minstd_rand |
+2**31-2 | +sizeof(int32_t) |
+0.4 | +- | +
rand48 |
+2**48-1 | +sizeof(uint64_t) |
+0.8 | +- | +
lrand48 (C library) |
+2**48-1 | +- | +0.2 | +global state | +
ecuyer1988 |
+approx. 2**61 | +2*sizeof(int32_t) |
+0.2 | +- | +
kreutzer1986 |
+? | +1368*sizeof(uint32_t) |
+0.6 | +- | +
hellekalek1995 |
+2**31-1 | +sizeof(int32_t) |
+0.03 | +good uniform distribution in several dimensions | +
mt11213b
+ | 2**11213-1 | +352*sizeof(uint32_t) |
+1 | +good uniform distribution in up to 350 dimensions | +
mt19937
+ | 2**19937-1 | +625*sizeof(uint32_t) |
+1 | +good uniform distribution in up to 623 dimensions | +
+As observable from the table, there is generally a +quality/performance/memory trade-off to be decided upon when choosing +a random-number generator. The multitude of generators provided in +this library allows the application programmer to optimize the +trade-off with regard to his application domain. Additionally, +employing several fundamentally different random number generators for +a given application of Monte Carlo simulation will improve the +confidence in the results. + +
+Note: These random number generators are not indended for use +in applications where non-deterministic random numbers are required. +See nondet_random.html for a choice +of (hopefully) non-deterministic random number generators. + +
+In this description, I have refrained from documenting those members +in detail which are already defined in the +concept documentation. + + +
<boost/random.hpp>
+namespace boost {
+ namespace detail {
+ template<class IntType, IntType m>
+ class const_mod;
+ template<class IntType, IntType a, IntType c, IntType m, IntType val>
+ class linear_congruential;
+ }
+ class rand48;
+ typedef detail::linear_congruential< /* ... */ > minstd_rand0;
+ typedef detail::linear_congruential< /* ... */ > minstd_rand;
+
+ namespace detail {
+ template<class DataType, int n, int m, int r, DataType a, int u,
+ int s, DataType b, int t, DataType c, int l, IntType val>
+ class mersenne_twister;
+ }
+ typedef detail::mersenne_twister< /* ... */ > mt11213b;
+ typedef detail::mersenne_twister< /* ... */ > mt19937;
+} // namespace boost
+
+
+
+detail::const_mod
+template<class IntType, IntType m>
+class detail::const_mod
+{
+public:
+ template<IntType c>
+ static IntType add(IntType x);
+
+ template<IntType a>
+ static IntType mult(IntType x);
+
+ template<IntType a, IntType c>
+ static IntType mult_add(IntType x);
+
+ static IntType invert(IntType x);
+private:
+ const_mod(); // don't instantiate
+};
+
+
+const_mod provides functions performing
+modular arithmetic, carefully avoiding overflows. All member
+functions are static; there shall be no objects of type
+const_mod<>.
+
+
+The template parameter IntType shall denote an integral
+type, m is the modulus.
+
+ +Note: For modulo multiplications with large m, a trick allows +fast computation under certain conditions, see +
+"A more portable FORTRAN random number generator", Linus Schrage, ACM +Transactions on Mathematical Software, Vol. 5, No. 2, June 1979, pp. 132-138 ++ + +
template<IntType c> static IntType add(IntType x)+ +Returns: (x+c) mod m + +
template<IntType a> static IntType mult(IntType x)+ +Returns: (a*x) mod m + +
template<IntType a, IntType c> static IntType +mult_add(IntType x)+ +Returns: (a*x+c) mod m + +
static IntType invert(IntType x)+ +Returns: i so that (a*i) mod m == 1 +
detail::linear_congruential
+template<class IntType, IntType a, IntType c, IntType m>
+class linear_congruential
+{
+public:
+ typedef IntType result_type;
+ static const IntType multiplier = a;
+ static const IntType increment = c;
+ static const IntType modulus = m;
+ static const bool has_fixed_range = true;
+ static const result_type min_value;
+ static const result_type max_value;
+ explicit linear_congruential_fixed(IntType x0 = 1);
+ // compiler-generated copy constructor and assignment operator are fine
+ void seed(IntType x0);
+ IntType operator()();
+};
+
+typedef detail::linear_congruential<long, 16807L, 0, 2147483647L,
+ 1043618065L> minstd_rand0;
+typedef detail::linear_congruential<long, 48271L, 0, 2147483647L,
+ 399268537L> minstd_rand;
+
+
+linear_congruential
+model a pseudo-random number
+generator. Linear congruential pseudo-random number generators
+are described in:
++"Mathematical methods in large-scale computing units", D. H. Lehmer, +Proc. 2nd Symposium on Large-Scale Digital Calculating Machines, +Harvard University Press, 1951, pp. 141-146 ++ +Let x(n) denote the sequence of numbers returned by +some pseudo-random number generator. Then for the linear congruential +generator, x(n+1) := (a * x(n) + c) mod m. Parameters for the +generator are x(0), a, c, m. + +The template parameter
IntType shall denote an
+integral type. It must be large enough to hold values a, c, and m.
+The template parameters a and c must be smaller than m.
+
+
+
+Note: The quality of the generator crucially depends on the
+choice of the parameters. User code should use one of the sensibly
+parameterized generators such as minstd_rand instead.
+
+For each choice of the parameters a, c, m, some distinct type is
+defined, so that the static members do not interfere with
+regard to the one definition rule.
+
+
explicit linear_congruential(IntType x0 = 1)+ +Effects: Constructs a +
linear_congruential generator with x(0) :=
+x0.
+
+void seed(IntType x0)+ +Effects: Changes the current value x(n) of the +generator to
x0.
+
+minstd_rand0 was originally suggested
+in
++A pseudo-random number generator for the System/360, P.A. Lewis, +A.S. Goodman, J.M. Miller, IBM Systems Journal, Vol. 8, No. 2, 1969, +pp. 136-146 ++ +It is examined more closely together with
minstd_rand in
++"Random Number Generators: Good ones are hard to find", Stephen +K. Park and Keith W. Miller, Communications of the ACM, Vol. 31, +No. 10, October 1988, pp. 1192-1201 ++ + +
rand48
+class rand48
+{
+public:
+ typedef int32_t result_type;
+ static const bool has_fixed_range = true;
+ static const int32_t min_value = 0;
+ static const int32_t max_value = 0x7fffffff;
+
+ explicit rand48(int32_t x0 = 1);
+ explicit rand48(uint64_t x0);
+ // compiler-generated copy ctor and assignment operator are fine
+ void seed(int32_t x0);
+ void seed(uint64_t x0);
+ int32_t operator()();
+};
+
+
+rand48 models a
+pseudo-random number
+generator. It uses the linear congruential algorithm with the
+parameters a = 0x5DEECE66D, c = 0xB, m = 2**48. It delivers identical
+results to the lrand48() function available on some
+systems (assuming lcong48 has not been called).
+
+It is only available on systems where uint64_t is provided.
+
+
rand48(int32_t x0)+ +Effects: Constructs a
rand48 generator
+with x(0) := (x0 << 16) | 0x330e.
+
+rand48(uint64_t x0)+ +Effects: Constructs a
rand48 generator
+with x(0) := x0.
+
+void seed(int32_t x0)+ +Effects: Changes the current value x(n) of the +generator to (
x0 << 16) | 0x330e.
+
+void seed(uint64_t x0)+ +Effects: Changes the current value x(n) of the +generator to
x0.
+
+
+detail::additive_combine
+template<class MLCG1, class MLCG2, typename MLCG1::result_type val>
+class detail::additive_combine
+{
+public:
+ typedef MLCG1 first_base;
+ typedef MLCG2 second_base;
+ typedef typename MLCG1::result_type result_type;
+ static const bool has_fixed_range = true;
+ static const result_type min_value = 1;
+ static const result_type max_value = MLCG1::max_value-1;
+ additive_combine();
+ additive_combine(typename MLCG1::result_type seed1,
+ typename MLCG2::result_type seed2);
+ result_type operator()();
+ bool validation(result_type x) const;
+};
+
+typedef detail::additive_combine<
+ detail::linear_congruential<int32_t, 40014, 0, 2147483563, 0>,
+ detail::linear_congruential<int32_t, 40692, 0, 2147483399, 0>,
+ /* unknown */ 0> ecuyer1988;
+
+
+
+additive_combine model a
+pseudo-random number
+generator. It combines two multiplicative linear congruential
+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 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.
+
+
+The template parameter val is the validation value
+checked by validation.
+
+
+
additive_combine()+ +Effects: Constructs an
additive_combine
+generator using the default constructors of the two base generators.
+
+additive_combine(typename MLCG1::result_type seed1, + typename MLCG2::result_type seed2)+ +Effects: Constructs an
additive_combine
+generator, using seed1 and seed2 as the
+constructor argument to the first and second base generator,
+respectively.
+
+
+ecuyer1988 was suggested in the above
+paper.
+
+
+detail::shuffle_output
+template<class UniformRandomNumberGenerator, int k,
+ class IntType = typename UniformRandomNumberGenerator::result_type,
+ typename UniformRandomNumberGenerator::result_type val = 0>
+class detail::shuffle_output
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef typename base_type::result_type result_type;
+ static const bool has_fixed_range = false;
+
+ shuffle_output();
+ template<class T> explicit shuffle_output(T seed);
+ explicit shuffle_output(const base_type & rng);
+ template<class T> void seed(T s);
+
+ result_type operator()();
+ result_type min() const;
+ result_type max() const;
+ bool validation(result_type) const;
+};
+
+
+shuffle_output model a
+pseudo-random number
+generator. It mixes the output of some (usually linear
+congruential) uniform random number generator to get better
+statistical properties. According to Donald E. Knuth, "The Art of
+Computer Programming, Vol. 2", the algorithm is described in
++"Improving a poor random number generator", Carter Bays and +S.D. Durham, ACM Transactions on Mathematical Software, Vol. 2, 1979, +pp. 59-64. ++The output of the base generator is buffered in an array of length +k. Every output X(n) has a second role: It gives an index into the +array where X(n+1) will be retrieved. Used array elements are +replaced with fresh output from the base generator. + +
+
+Template parameters are the base generator and the array length k,
+which should be around 100. As an implementation detail, the template
+parameter IntType shall denote an integer-like type which
+is large enough to hold integer numbers of value k *
+base_type::max(). The template parameter
+val is the validation value checked by
+validation.
+
+
+
shuffle_output()+ +Effects: Constructs a
shuffle_output
+generator by invoking the default constructor of the base generator.
++Complexity: Exactly k+1 invocations of the base +generator. + +
template<class T> explicit shuffle_output(T seed)+ +Effects: Constructs a
shuffle_output
+generator by invoking the one-argument constructor of the base
+generator with the parameter seed.
++Complexity: Exactly k+1 invocations of the base +generator. + +
explicit shuffle_output(const base_type & rng)+ +Precondition: The template argument +
UniformRandomNumberGenerator shall denote a
+CopyConstructible type.
+
+Effects: Constructs a shuffle_output
+generator by using a copy of the provided generator.
+
+Complexity: Exactly k+1 invocations of the base +generator. + +
template<class T> void seed(T s)+ +Effects: Invokes the one-argument
seed
+method of the base generator with the parameter seed and
+re-initializes the internal buffer array.
++Complexity: Exactly k+1 invocations of the base +generator. + + +
kreutzer1986 was suggested in:
++"System Simulation: programming Styles and Languages (International +Computer Science Series)", Wolfgang Kreutzer, Addison-Wesley, December +1986. ++ + +
detail::inversive_congruential
+template<class IntType, IntType a, IntType b, IntType p>
+class detail::inversive_congruential
+{
+public:
+ typedef IntType result_type;
+ static const bool has_fixed_range = true;
+ static const result_type min_value = (b == 0 ? 1 : 0);
+ static const result_type max_value = p-1;
+ static const result_type multiplier = a;
+ static const result_type increment = b;
+ static const result_type modulus = p;
+ explicit inversive_congruential(IntType y0 = 1);
+ void seed(IntType y0);
+ IntType operator()();
+};
+
+typedef detail::inversive_congruential<int32_t, 9102, 2147483647-36884165, 2147483647> hellekalek1995;
+
+
+inversive_congruential model a
+pseudo-random number
+generator. It uses the inversive congruential algorithm (ICG)
+described in
++"Inversive pseudorandom number generators: concepts, results and +links", Peter Hellekalek, In: "Proceedings of the 1995 Winter +Simulation Conference", C. Alexopoulos, K. Kang, W.R. Lilegdon, and +D. Goldsman (editors), 1995, pp. 255-262. +ftp://random.mat.sbg.ac.at/pub/data/wsc95.ps ++ +The output sequence is defined by x(n+1) = (a*inv(x(n)) - b) (mod p), +where x(0), a, b, and the prime number p are parameters of the +generator. The expression inv(k) denotes the multiplicative inverse +of k in the field of integer numbers modulo p, with inv(0) := 0. + +
+
+The template parameter IntType shall denote a signed
+integral type large enough to hold p; a, b, and p are the parameters
+of the generators.
+
+Note: The implementation currently uses the Euclidian +Algorithm to compute the multiplicative inverse. Therefore, the +inversive generators are about 10-20 times slower than the others (see +section"performance"). However, the paper +talks of only 3x slowdown, so the Euclidian Algorithm is probably not +optimal for calculating the multiplicative inverse. + + +
inversive_congruential(IntType y0 = 1)+ +Effects: Constructs an +
inversive_congruential generator with
+y0 as the initial state.
+
+void seed(IntType y0)+ +Effects: +Changes the current state to
y0.
+
+
+hellekalek1995 was suggested in the
+above paper.
+
+
+detail::mersenne_twister
+template<class DataType, int n, int m, int r, DataType a, int u,
+int s, DataType b, int t, DataType c, int l, IntType val>
+class detail::mersenne_twister
+{
+public:
+ typedef DataType result_type;
+ static const bool has_fixed_range = true;
+ static const result_type min_value;
+ static const result_type max_value;
+ mersenne_twister();
+ explicit mersenne_twister(DataType value);
+ template<class Generator> explicit mersenne_twister(Generator & gen);
+ // compiler-generated copy ctor and assignment operator are fine
+ void seed();
+ void seed(DataType value);
+ template<class Generator> void seed(Generator & gen);
+ result_type operator()();
+ bool validation(result_type) const;
+};
+
+typedef mersenne_twister<uint32_t,351,175,19,0xccab8ee7,11,7,0x31b6ab00,15,0xffe50000,17, /* unknown */ 0> mt11213b;
+typedef mersenne_twister<uint32_t,624,397,31,0x9908b0df,11,7,0x9d2c5680,15,0xefc60000,18, 3346425566U> mt19937;
+
+
+mersenne_twister 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. +http://www.math.keio.ac.jp/matumoto/emt.html ++ +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. +
mt19937 instead.
+mt11213b requires about
+1408 bytes and mt19937 requires about 2496 bytes.
+
+mersenne_twister()+ +Effects: Constructs a
mersenne_twister
+and calls seed().
+
+explicit mersenne_twister(DataType value)+ +Effects: Constructs a
mersenne_twister
+and calls seed(value).
+
+template<class Generator> explicit mersenne_twister(Generator & gen)+ +Effects: Constructs a
mersenne_twister
+and calls seed(gen).
+
+void seed()+ +Effects: Calls
seed(4357).
+
+void seed(DataType value)+ +Effects: Constructs a +
linear_congruential<uint32_t, 69069, 0, 0, 0>
+generator with the constructor parameter
+value and calls seed with it.
+
+template<class Generator> void seed(Generator & gen)+ +Effects: Sets the state of this +
mersenne_twister to the values returned by n
+invocations of gen.
+
+
+
+Complexity: Exactly n invocations of gen.
+
+
mt11213b and mt19937 are
+from the paper cited above.
+
+
++ +
| class | time per invocation [usec] |
|---|---|
| rand48 | 0.096 |
| rand48 run-time configurable | 0.697 |
| lrand48 glibc 2.1.2 | 0.844 |
| minstd_rand | 0.174 |
| ecuyer1988 | 0.445 |
| kreutzer1986 | 0.249 |
| hellekalek1995 (inversive) | 4.895 |
| mt11213b | 0.165 |
| mt19937 | 0.165 |
| mt19937 original | 0.185 |
+The measurement error is estimated at +/- 10 nsec. + +
+
<boost/random.hpp>
+namespace boost {
+ template<class UniformRandomNumberGenerator, class IntType = long>
+ class random_number_generator;
+ template<class Generator>
+ class generator_iterator;
+} // namespace boost
+
+
+
+random_number_generator
+template<class UniformRandomNumberGenerator, class IntType = long>
+class random_number_generator
+{
+public:
+ typedef UniformRandomNumberGenerator base_type;
+ typedef IntType argument_type;
+ typedef IntType result_type;
+ random_number_generator(base_type & rng);
+ result_type operator()(argument_type n);
+};
+
+
+random_number_generator
+model a RandomNumberGenerator (std:25.2.11 [lib.alg.random.shuffle]).
+On each invocation, it returns a uniformly distributed integer in
+the range [0..n).
+
+The template parameter IntType shall denote some
+integer-like value type.
+
+ +Note: I consider it unfortunate that the C++ Standard uses +the name RandomNumberGenerator for something rather specific. + +
random_number_generator(base_type & rng)+ +Effects: Constructs a +
random_number_generator functor with the given uniform
+random number generator as the underlying source of random numbers.
+
+result_type operator()(argument_type n)+ +Returns: The value of +
uniform_int<base_type>(rng, 0, n-1)().
+
+
+generator_iterator
+template<class Generator>
+class generator_iterator
+ : equality_comparable<generator_iterator<Generator> >,
+ incrementable<generator_iterator<Generator> >,
+ dereferenceable<generator_iterator<Generator>,
+ typename Generator::result_type>
+{
+public:
+ typedef typename Generator::result_type value_type;
+ typedef std::ptrdiff_t difference_type;
+ typedef const typename Generator::result_type * pointer;
+ typedef const typename Generator::result_type & reference;
+ typedef std::input_iterator_tag iterator_category;
+
+ explicit generator_iterator(Generator & g);
+ generator_iterator& operator++();
+ reference operator*() const;
+ friend bool operator==(const generator_iterator<Generator>& x,
+ const generator_iterator<Generator>& y);
+};
+
+
+generator_iterator
+satisfy the input iterator requirements (std:24.1.1
+[lib.input.iterators]). It allows iterator-like access to a
+generator, e.g. a NumberGenerator. Note that all distribution
+functions now satisfy the input iterator requirements as-is. However,
+the base generators do not.
+
+explicit generator_iterator(Generator & g)+ +Effects: Constructs a
generator_iterator
+with g as the underlying generator. Invokes the
+underlying generator functor.
+
+generator_iterator& operator++()+ +Effects: Invokes the underlying generator functor. +
+Returns: *this
+
+
reference operator*() const+ +Returns: The value of the last invocation of the +underlying generator functor. + +
bool operator==(const generator_iterator<Generator>& x, + const generator_iterator<Generator>& y)+ +Returns:
true iff the x and
+y have been initialized with a reference to the same
+generator functor and *x == *y.
+
+
++