Introduction

Forward to Installing RandomLib. Up to Contents.

RandomLib is a C++ class which implements the Mersenne Twister random number generator, MT19937 and the SIMD-oriented Fast Mersenne Twister random number generator, SFMT19937. For a description of MT19937 see
Makoto Matsumoto and Takuji Nishimura,
Mersenne Twister: A 623-Dimensionally Equidistributed Uniform Pseudo-Random Number Generator,
ACM TOMACS 8, 3–30 (1998).
For a description of SFMT19937 see
Mutsuo Saito,
An Application of Finite Field: Design and Implementation of 128-bit Instruction-Based Fast Pseudorandom Number Generator,
Master's Thesis, Dept. of Math., Hiroshima University (Feb. 2007),
Mutsuo Saito and Makoto Matsumoto,
SIMD-oriented Fast Mersenne Twister: a 128-bit Pseudorandom Number Generator,
accepted in the proceedings of MCQMC2006.

MT19937 and SFMT19937 are high-quality random number generators with an exceptionally large period 2¹⁹⁹³⁷ − 1 or about 10⁶⁰⁰¹; it passes all current tests for randomness.

The emphasis in this implementation is on providing a reliable source of random numbers for scientific applications where there's a premium on

• accuracy – all the results from Random are exact assuming that the underlying generators are perfect. Thus a random integer in [0, n) is given by Integer(n) which guarantees that all possible results are equally likely. Similarly FloatN() is equivalent to sampling a random number in (0,1) and exactly rounding it to the nearest representable double.
• repeatability – extensive facilities for managing the seed for the generator. It's easy to seed the generators in a parallel application in a systematic way to give repeatable results.
• portability – the same results are obtained on different platforms.
• efficiency – template functions provide fast general code.
• ease of use – the interface makes it difficult to misuse the generator with most usage errors being caught at compile time.

Random provides the basic functionality of the MT19937 and SFMT19937 random generator, converting the random data into various formats. It provides methods for returning random integers of various sizes (short int, int, long int, etc.), for returning random integers in the semi-closed interval [0,n) and the closed interval [m,n].

You can obtain uniform random reals at various precisions; these are defined by rounding a random number uniformly sampled in (0,1) and exactly rounding it (down, up, or nearest) to a subset of representable reals. Thus Float() is the result of rounding a random number in (0,1) down to the nearest representable double.

Boolean() returns true with probability 1/2. Prob(x) returns true with probability x. Prob(a, b) returns true with probability a/b.

Bits<n>() returns n bits of randomness in a bitset<n>.

In addition, Random provides facilities for setting seeds, for selecting a "random" seed, for saving and restoring its state, and for jumping the generator forwards and backwards.

NormalDistribution and ExponentialDistribution are classes which sample from the normal and exponential distributions. RandomSelect selects from an arbitrary discrete distribution.

Finally, RandomNumber provides support for infinite precision random numbers. These are used by ExactExponential and ExactNormal which sample exactly from the exponential and normal distributions. DiscreteNormal and DiscreteNormalAlt sample exactly from the discrete normal distribution (important in some applications in cryptography).

Both 32-bit and 64-bit versions of MT19937 and SFMT19937 are provided with the 32-bit version of SFMT19937 being the default generator. See Selection of default generator for a comparison between the various generators and how to change the default generator.

RandomLib depends on no external libraries (other than the standard C++ library). However, boost serialization can optionally be used for saving and restoring the state of the generator. The example code for parallelization, RandomThread.cpp, uses OpenMP.

My interest in random number generators extends back through much of my professional career in plasma physics, chaos theory, and computational chemistry. I wrote a random number library for Fortran 77 and Fortran 90 which implemented one of Knuth's recommended random number generators (see http://w3.pppl.gov/ntcc/RNG/). With the current C++ random number library, I switched to a more robust underlying generator, SFMT19937, provided more flexible seeding options, and provided exact implementations for uniform real and integer distributions.

Undoubtedly, bugs lurk in this code and in the documentation. Please report any you find to charl.nosp@m.es@k.nosp@m.arney.nosp@m..com.

Forward to Installing RandomLib. Up to Contents.