Code organization

Back to Getting started. Forward to The seed. Up to Contents.

Random manipulates the data arrays, the seed and the state. These are managed by the following classes, which are all defined in the RandomLib namespace:

• RandomSeed. This provides low-level facilities for changing and reporting the seed.
• RandomEngine<Algorithm, Mixer>. This is derived from RandomSeed. This provides facilities for managing the state, returning the next random number, stepping the state, saving and restoring the state and the seed. It uses two classes specified as template parameters Algorithm and Mixer. These classes contain no state and are invoked through static methods.
  • Algorithm. This provides a mechanism for producing the next batch of state given the current state. This is what most people understand by a random number algorithm. In addition, it provides a facility to convert an arbitrary state (as given by Mixer) into a legal state and to "temper" the state immediately prior to being returned by RandomEngine. This package provides definitions of the following Algorithms
    • MT19937<Random_u32> – 32-bit version of MT19937
    • MT19937<Random_u64> – 64-bit version of MT19937
    • SFMT19937<Random_u32> – 32-bit version of SFMT19937
    • SFMT19937<Random_u64> – 64-bit version of SFMT19937
  • Mixer. This converts the current seed into an initial state by some suitable mixing procedure. For more details see The seed. This package provides the following definitions of the following Mixers:
    • MixerMT0<Random_u32> – init_by_array from 32-bit version of MT19937
    • MixerMT0<Random_u64> – init_by_array from 64-bit version of MT19937
    • MixerMT1<Random_u32> – improved version of MixerMT0<Random_u32>
    • MixerMT1<Random_u64> – improved version of MixerMT0<Random_u64>
    • MixerSFMT – init_by_array from SFMT19937
    only MixerSFMT is recommended for production use.
• RandomGenerator is defined by

  typedef RandomEngine<SFMT19937<Random_u32>, MixerSFMT> RandomGenerator;

  This is the standard user interface for accessing the random number generator to provide random numbers in 32-bit and 64-bit chunks. See Selection of default generator for how to access the MT19937 generator or the 64-bit versions of these generators.
• RandomCanonical. This accepts a random generator as a template parameter and is a derived class of that generator. RandomCanonical converts the random bits from the underlying generator into usable data: integers in specific ranges, real numbers at various resolutions, etc.
• Random is defined by

  typedef RandomCanonical<RandomGenerator> Random; 

• RandomType is a utility template class which is used to couple a bit-width and an unsigned C++ type. The following typedefs are included

  typedef RandomType<32, uint32_t> Random_u32;
  typedef RandomType<64, uint64_t> Random_u64; 

For most purposes, users should ignore the existence of RandomSeed, RandomEngine, RandomGenerator, and RandomCanonical and access all the capabilities of these classes via thru the class Random which inherits all the needed functionality of its base classes. This documentation reflects this recommendation. (In restricted applications, a user might wish to interface to the library via the lower-level RandomGenerator class as a source of random words.)

Unfortunately the relation between this classes is sufficiently complicated to defeat doxygen's indexing capabilities; if you need to look up the definition of one of Random's member functions, you can refer to the brief index in Function index.

Finally, distributions such as the normal and exponential distribution are provided by the classes NormalDistribution and ExponentialDistribution. They access the random data by being passed a Random object as an argument to operator().

Several errors in using RandomLib are caught at compile time. Runtime errors are signaled by throwing RandomErr exceptions with a explanatory message.

RandomLib includes facilities for sampling from the uniform, exponential, and normal distributions using MPFR (version 3.0 and later). These are a header-only interface (the header names all being with "MPFR") which use MPFR's random number generator and may be used apart from the rest of RandomLib. MPFRExample.cpp illustrates their use. See MPFR interface for more information.

These routines have been developed and tested with g++ version 4.x under Linux 2.6.x on 32-bit and 64-bit Intel and 64-bit AMD CPUs, MS Visual Studio 2005 and 2008, under Windows. Earlier versions of this library were tested with g++ under Darwin on a PowerPC and under Solaris on 64-bit SPARC platforms. Porting to other platforms with a standard C++ compiler and template library should be straightforward provided that the radix for integer and real types is 2.

A note about portability. For the most part, the code uses standard C++. System dependencies creep into the computation of SeedVector and SeedWord (e.g., to access the PID and the high-precision clock). In addition, it's assumed that unsigned integers can be cast into signed integers preserving the bit pattern (assuming a twos-complement convention for signed numbers). Visual Studio 2005, 2008, 2010 compiling for a 32-bit machines have a bug in their standard template library implementations which prevent you from creating vectors of SFMT19937 generators if they are compiled with SSE2 instructions (via HAVE_SSE2); this prevents you from using, for example, a std::vector to hold such objects. To circumvent this bug you will need to create your own containers which call new and delete explicitly. (RandomLib includes new and new[] operators for SFMT19937 which return correctly aligned blocks of memory.) See RandomThread.cpp for an example of a simple fixed-size container.

Back to Getting started. Forward to The seed. Up to Contents.