[boost] Changes to the random number library

From: Jens Maurer (Jens.Maurer_at_[hidden])
Date: 2002-10-01 18:10:34

I'm progressing towards a paper for the ISO C++ committee
proposing to include a random number facility based on
Boost.Random in the C++ standard library technical report.

I've checked in the current work-in-progress state
of the proposal to (CVS) boost/libs/random/wg21-proposal.html

I'm still unsure about the choice of engines for standardization.
Some criteria plus an overview of other libraries is provided
in the above proposal.

For distributions, I believe my survey of what other libraries
provide leads to the choice of these "advanced" distributions:

 - exponential
 - normal
 - gamma
 - poisson
 - binomial
 - geometric
 - bernoulli

The other distributions will continue to be available in
Boost.Random, it's just that other distributions won't be
part of the proposal for an C++ standard library extension.
(The uniform stuff is on top, of course.)

I've checked in the following changes to Boost.Random:

 - Added the "ranlux" generator (ranlux.hpp), by request of
Marc Fischler
(The generator actually consists of the building blocks of
a subtract-with-carry generator (subtract_with_carry.hpp) and
some blockwise discarding (discard_block.hpp) on top.)

 - Added a "linear_feedback_shift" generator.

 - Added the xor_combine compound generator.  This is
useful to combine several generators on a bit level.

 - All generators now have a constructor and seed()
function that take an iterator range.  The provided
integer values can be used to initialize the full seed
of an arbitrary generator.  Also, this is a uniform
seeding method, also suitable for compound generators
such as xor_combine that need to seed two source
generators of arbitrary state size.  I believe this
interface provides the necessary uniform seeding
without resorting to global arrays of "good" uint32_t
seeds or somesuch.

 - Gamma, Poisson, and Binomial distributions have been
added.  (Typed in from Knuth, I hope it's correct.  They
are not exactly efficient.)

 - Generators didn't have an operator!= before, by omission

More inspection capability:
 - base() member function for distributions.  This
returns a reference to the underlying generator.

 - reset() member function for distributions.  This
discards any generator state that might be cached
in the distribution (this happens in normal_distribution,
for example).   When saving and later restoring the
underlying generator's state, this feature allows to
setup at a defined system state when going on with the
simulation.

 - distributions have accessor functions to retrieve
their constructor parameters (not everywhere, yet).

 - random_device (in nondet_random.hpp) now has an
entropy() function that gives information about
the "randomness" of the return numbers.  If no
"real" randomness is available on some platform,
a pseudo-random number generator can be used, with
entropy() == 0.

 - The naming convention is now that floating-point
valued generators are named lagged_fibonacci_01
and subtract_with_carry_01 (i.e. a _01 suffix on
the integer generator).  The lagged_fibonacci didn't
adhere to this.  I've changed it, that might require
changes to your code.  I cannot handle integer and
floating-point generators with the same class, because
the integer ones usually have min_value and max_value
static constants, but the floating-point ones don't.
I avoided a (partial) specialization, in memory of
vector<bool>.

 - mersenne_twister was missing the word bitsize
(now, it has enough interface information to also
be able to make it work on implementations with
odd-sized words, e.g. 36 bits)

 - lagged_fibonacci was missing the modulus as well.
This is provided by giving the log2(modulus); there
are only lagged_fibonacci generators in use that use
powers-of-two here.

 - validation() is now static. It doesn't use anything
from the generator.

 - uniform_smallint should now be usable with
floating-point generators

The following features are deprecated and will be
removed after boost release 1.30.

 - template<class T> seed(T)  functions and constructors
on compound generators.  Those are replaced by the
iterator-based seeding.

 - template<class Generator> seed(Generator&) functions
and constructors on large-state generators (lagged_fibonacci,
mersenne_twister).  Those are replaced by the
iterator-based seeding.

 - validation().  I've thought a lot about this
feature.  The current state of affairs is that
the generators have an additional template value parameter
to set the value "val" of the 10001th number of the sequence.
(Floating-point generators need more effort, because
template value parameters can't be of floating-point type.)
The validation(x) function just amounts to "x == val",
which seems somewhat trivial.  The specification of the
generator will still contain the validation value in
prose text, so testing by any user is still possible,
but not provided as an intrinsic library feature.
libs/random/random_test.cpp shows an example how to do
this (tomorrow).

 - operator== for distributions has vague semantics
and will be removed.
Comparing the parameters of the distribution is about
the only sensible thing to do, but those are usually
floating-point numbers.  Comparing them is an entire
art, so better not addressed in the random number
library.

The Boost.Random documentation is currently not up-to-date
regarding these changes.

Jens Maurer