uniform_smallintuniform_intuniform_01uniform_realbernoulli_distributiongeometric_distributiontriangle_distributionexponential_distributionnormal_distributionlognormal_distributionuniform_on_sphereIn addition to the random number generators, this library provides distribution functions which map one distribution (often a uniform distribution provided by some generator) to another.
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
The distribution functions no longer satisfy the input iterator requirements (std:24.1.1 [lib.input.iterators]), because this is redundant given the Generator interface and imposes a run-time overhead on all users. Moreover, a Generator interface appeals to random number generation as being more "natural". Use an iterator adaptor if you need to wrap any of the generators in an input iterator interface.
All of the distribution functions described below store a non-const reference to the underlying source of random numbers. Therefore, the distribution functions are not Assignable. However, they are CopyConstructible. Copying a distribution function will copy the parameter values. Furthermore, both the copy and the original will refer to the same underlying source of random numbers. Therefore, both the copy and the original will obtain their underlying random numbers from a single sequence.
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 IntType = int>
class uniform_smallint;
template<class IntType = int>
class uniform_int;
template<class RealType = double>
class uniform_01;
template<class RealType = double>
class uniform_real;
// discrete distributions
template<class RealType = double>
class bernoulli_distribution;
template<class IntType = int>
class geometric_distribution;
// continuous distributions
template<class RealType = double>
class triangle_distribution;
template<class RealType = double>
class exponential_distribution;
template<class RealType = double>
class normal_distribution;
template<class RealType = double>
class lognormal_distribution;
template<class RealType = double,
class Cont = std::vector<RealType> >
class uniform_on_sphere;
}
uniform_smallint
#include <boost/random/uniform_smallint.hpp>
template<class IntType = int>
class uniform_smallint
{
public:
typedef IntType input_type;
typedef IntType result_type;
static const bool has_fixed_range = false;
uniform_smallint(IntType min, IntType max);
result_type min() const;
result_type max() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
The distribution function uniform_smallint models a
random distribution. 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 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(IntType min, IntType max)
Effects: Constructs a uniform_smallint
functor. min and max are the lower and upper
bounds of the output range, respectively.
uniform_int
#include <boost/random/uniform_int.hpp>
template<class IntType = int>
class uniform_int
{
public:
typedef IntType input_type;
typedef IntType result_type;
static const bool has_fixed_range = false;
explicit uniform_int(IntType min = 0, IntType max = 9);
result_type min() const;
result_type max() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng, result_type n);
};
The distribution function uniform_int models a random distribution. 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(IntType min = 0, IntType max = 9)
Requires: min <= max
Effects: Constructs a uniform_int object.
min and max are the parameters of the
distribution.
result_type min() const
Returns: The "min" parameter of the distribution.
result_type max() const
Returns: The "max" parameter of the distribution.
result_type operator()(UniformRandomNumberGenerator& urng, result_type
n)
Returns: A uniform random number x in the range 0 <=
x < n. [Note: This allows a variate_generator object
with a uniform_int distribution to be used with
std::random_shuffe, see [lib.alg.random.shuffle]. ]
uniform_01
#include <boost/random/uniform_01.hpp>
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;
};
The distribution function uniform_01 models a random distribution. 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
#include <boost/random/uniform_real.hpp>
template<class RealType = double>
class uniform_real
{
public:
typedef RealType input_type;
typedef RealType result_type;
static const bool has_fixed_range = false;
uniform_real(RealType min = RealType(0), RealType max = RealType(1));
result_type min() const;
result_type max() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
The distribution function uniform_real models a random distribution. 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.
uniform_real(RealType min = RealType(0), RealType max = RealType(1))
Requires: min <= max
Effects: Constructs a uniform_real object;
min and max are the parameters of the
distribution.
result_type min() const
Returns: The "min" parameter of the distribution.
result_type max() const
Returns: The "max" parameter of the distribution.
bernoulli_distribution
#include <boost/random/bernoulli_distribution.hpp>
template<class RealType = double>
class bernoulli_distribution
{
public:
typedef int input_type;
typedef bool result_type;
explicit bernoulli_distribution(const RealType& p = RealType(0.5));
RealType p() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template bernoulli_distribution
model a random distribution.
Such a random distribution produces bool values distributed
with probabilities P(true) = p and P(false) = 1-p. p is the parameter of
the distribution.
bernoulli_distribution(const RealType& p = RealType(0.5))
Requires: 0 <= p <= 1
Effects: Constructs a bernoulli_distribution
object. p is the parameter of the distribution.
RealType p() const
Returns: The "p" parameter of the distribution.
geometric_distribution
#include <boost/random/geometric_distribution.hpp>
template<class UniformRandomNumberGenerator, class IntType = int>
class geometric_distribution
{
public:
typedef RealType input_type;
typedef IntType result_type;
explicit geometric_distribution(const RealType& p = RealType(0.5));
RealType p() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template geometric_distribution
model a random distribution.
A geometric_distribution random distribution produces integer
values i >= 1 with p(i) = (1-p) * pi-1. p is the
parameter of the distribution.
geometric_distribution(const RealType& p = RealType(0.5))
Requires: 0 < p < 1
Effects: Constructs a geometric_distribution
object; p is the parameter of the distribution.
RealType p() const
Returns: The "p" parameter of the distribution.
triangle_distribution
#include <boost/random/triangle_distribution.hpp>
template<class RealType = double>
class triangle_distribution
{
public:
typedef RealType input_type;
typedef RealType result_type;
triangle_distribution(result_type a, result_type b, result_type c);
result_type a() const;
result_type b() const;
result_type c() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template triangle_distribution
model a random distribution.
The returned floating-point values x satisfy a <= x
<= c; x has a triangle distribution, where
b is the most probable value for x.
triangle_distribution(result_type a, result_type b, result_type c)
Effects: Constructs a
triangle_distribution functor. a, b, c are the
parameters for the distribution.
exponential_distribution
#include <boost/random/exponential_distribution.hpp>
template<class RealType = double>
class exponential_distribution
{
public:
typedef RealType input_type;
typedef RealType result_type;
explicit exponential_distribution(const result_type& lambda);
RealType lambda() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template exponential_distribution
model a random distribution.
Such a distribution produces random numbers x > 0 distributed with
probability density function p(x) = lambda * exp(-lambda * x), where lambda
is the parameter of the distribution.
exponential_distribution(const result_type& lambda = result_type(1))
Requires: lambda > 0
Effects: Constructs an
exponential_distribution object with rng as the
reference to the underlying source of random numbers. lambda
is the parameter for the distribution.
RealType lambda() const
Returns: The "lambda" parameter of the distribution.
normal_distribution
#include <boost/random/normal_distribution.hpp>
template<class RealType = double>
class normal_distribution
{
public:
typedef RealType input_type;
typedef RealType result_type;
explicit normal_distribution(const result_type& mean = 0,
const result_type& sigma = 1);
RealType mean() const;
RealType sigma() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template normal_distribution model
a random distribution. Such
a distribution produces random numbers x distributed with probability
density function p(x) = 1/sqrt(2*pi*sigma) * exp(- (x-mean)2 /
(2*sigma2) ), where mean and sigma are the parameters of the
distribution.
explicit normal_distribution(const result_type& mean = 0,
const result_type& sigma = 1);
Requires: sigma > 0
Effects: Constructs a normal_distribution
object; mean and sigma are the parameters for the
distribution.
RealType mean() const
Returns: The "mean" parameter of the distribution.
RealType sigma() const
Returns: The "sigma" parameter of the distribution.
lognormal_distribution
#include <boost/random/lognormal_distribution.hpp>
template<class RealType = double>
class lognormal_distribution
{
public:
typedef typename normal_distribution<RealType>::input_type
typedef RealType result_type;
explicit lognormal_distribution(const result_type& mean = 1.0,
const result_type& sigma = 1.0);
RealType& mean() const;
RealType& sigma() const;
void reset();
template<class UniformRandomNumberGenerator>
result_type operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template lognormal_distribution
model a random distribution.
Such a distribution produces random numbers with p(x) = 1/(x * normal_sigma
* sqrt(2*pi)) * exp( -(log(x)-normal_mean)2 /
(2*normal_sigma2) ) for x > 0, where normal_mean =
log(mean2/sqrt(sigma2 + mean2)) and
normal_sigma = sqrt(log(1 + sigma2/mean2)).
lognormal_distribution(const result_type& mean,
const result_type& sigma)
Effects: Constructs a
lognormal_distribution functor. mean and
sigma are the mean and standard deviation of the lognormal
distribution.
uniform_on_sphere
#include <boost/random/uniform_on_sphere.hpp>
template<class RealType = double,
class Cont = std::vector<RealType> >
class uniform_on_sphere
{
public:
typedef RealType input_type;
typedef Cont result_type;
explicit uniform_on_sphere(int dim = 2);
void reset();
template<class UniformRandomNumberGenerator>
const result_type & operator()(UniformRandomNumberGenerator& urng);
};
Instantiations of class template uniform_on_sphere model a
random distribution. Such a
distribution produces random numbers uniformly distributed on the unit
sphere of arbitrary dimension dim. 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(int dim = 2)
Effects: Constructs a uniform_on_sphere
functor. dim is the dimension of the sphere.
Revised 05 December, 2006
Copyright © 2000-2004 Jens Maurer
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)