![]() |
Home | Libraries | People | FAQ | More |
Random numbers are required in a number of different problem domains, such as
The Boost Random Number Generator Library provides a framework for random number generators with well-defined properties so that the generators can be used in the demanding numerics and security domains. For a general introduction to random numbers in numerics, see
"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:
All variations have some properties in common, the concepts (in the STL sense) is called UniformRandomNumberGenerator. This concept will be defined in a subsequent section.
The goals for this library are the following:
A uniform random number generator provides a sequence of random numbers uniformly distributed on a given range. The range can be compile-time fixed or available (only) after run-time construction of the object.
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.
Table 1.1. UniformRandomNumberGenerator requirements
expression |
return type |
pre/post-condition |
---|---|---|
|
|
|
|
|
- |
|
|
tight lower bound on the set of all values returned by |
|
|
if |
The member functions min
,
max
, and operator()
shall have amortized constant time complexity.
![]() |
Note |
---|---|
For integer generators (i.e. integer 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
Rationale: |
A non-deterministic uniform random number generator is a UniformRandomNumberGenerator that is based on some stochastic process. Thus, it provides a sequence of truly-random numbers. Examples for such processes are nuclear decay, noise of a Zehner diode, tunneling of quantum particles, rolling a die, drawing from an urn, and tossing a coin. Depending on the environment, inter-arrival times of network packets or keyboard events may be close approximations of stochastic processes.
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 an outside attacker from guessing the numbers and thus obtaining 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. |
A pseudo-random number generator is a UniformRandomNumberGenerator
which provides a deterministic sequence of pseudo-random numbers, based
on some algorithm and internal state. Linear
congruential
and inversive
congruential
generators are examples of such pseudo-random
number generators. Often, these generators are very sensitive to
their parameters. In order to prevent wrong implementations from being
used, an external testsuite should check that the generated sequence and
the validation value provided do indeed match.
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, u
is a value of X
, i
is a value of integral type, s
is a value of a type which models
SeedSeq,
and j
a value of type
unsigned long
long
.
Table 1.2. PseudoRandomNumberGenerator requirements
expression |
return type |
pre/post-condition |
---|---|---|
|
- |
creates a generator with a default seed. |
|
- |
creates a generator seeding it with the integer |
|
- |
creates a generator setting its initial state from the SeedSeq
|
|
|
sets the current state to be identical to the state that would be created by the corresponding constructor. |
|
|
Advances the generator by |
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 shall also model the
Streamable concept, i.e. implement operator<<
and operator>>
. 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 should 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 non-zero arguments constructor(s) and the |
A SeedSeq represents a sequence of values that can be used to set the initial
state of a PseudoRandomNumberGenerator.
i
and j
are RandomAccessIterators whose value_type
is an unsigned integer type with at least 32 bits.
Table 1.3. SeedSeq requirements
expression |
return type |
pre/post-condition |
complexity |
---|---|---|---|
|
void |
stores 32-bit values to all the elements in the iterator range
defined by |
O(j - i) |
The class seed_seq
and every UniformRandomNumberGenerator
provided by the library are models of SeedSeq.
A random distribution produces random numbers distributed according to
some distribution, given uniformly distributed random values as input.
In the following table, X
denotes a random distribution class returning objects of type T
, u
is a value of X
, x
and y
are (possibly const) values of X
,
P
is the param_type
of the distribution, p
is a value of P
,
and e
is an lvalue of an
arbitrary type that meets the requirements of a UniformRandomNumberGenerator,
returning values of type U
.
Table 1.4. Random distribution requirements (in addition to CopyConstructible, and Assignable)
expression |
return type |
pre/post-condition |
complexity |
---|---|---|---|
|
|
- |
compile-time |
|
|
A type that stores the parameters of the distribution, but not
any of the state used to generate random variates. |
compile-time |
|
|
Initializes a distribution from its parameters |
O(size of state) |
|
|
subsequent uses of |
constant |
|
|
the sequence of numbers returned by successive invocations with
the same object |
amortized constant number of invocations of |
|
|
Equivalent to X(p)(e), but may use a different (and presumably more efficient) implementation |
amortized constant number of invocations of |
|
|
Returns the parameters of the distribution |
O(size of state) |
|
void |
Sets the parameters of the distribution |
O(size of state) |
|
|
returns the minimum value of the distribution |
constant |
|
|
returns the maximum value of the distribution |
constant |
|
|
Indicates whether the two distributions will produce identical sequences of random variates if given equal generators |
O(size of state) |
|
|
|
O(size of state) |
|
|
writes a textual representation for the parameters and additional
internal data of the distribution |
O(size of state) |
|
|
restores the parameters and additional internal data of the distribution
|
O(size of state) |
Additional requirements: The sequence of numbers produced by repeated invocations
of x(e)
does
not change whether or not os
<< x
is invoked between any of the invocations x(e)
.
If a textual representation is written using os
<< x
and that representation is restored into the same or a different object
y
of the same type using
is >>
y
, repeated invocations of y(e)
produce the same sequence of random numbers
as would repeated invocations of x(e)
.