6.5 Random

The Random class is a pseudo random number generator (PRNG) base on the Mersenne Twister algorithm. The Mersenne Twister algorithm was developed by Makoto Matsumoto, and Takuji Nishimura, and has a period of 2¹⁹⁹³⁷ - 1. Further description and properties of the algorithm can be found at http://www.math.keio.ac.jp/~matumoto/emt.html. This implementation of the Mersenne Twister PRNG provides the following features:

A best as possible optimized algorithm allowing to draw 95 million 32 bit unsigned integer random numbers on a Linux box running on an Intel P4 1.4 GHz CPU.
Seeding by means of a random device /dev/urandom if available.
8, 16, 32, and 64 bit random signed or unsigned integers.
Maximum specification for 8, 16, 32, and 64 bit unsigned integers.
Real random numbers in double format, with maximum specification, and open or close interval specification.

Drawing random integers in a given interval is much slower than drawing them in their respective complete interval. This is because the chose algorithm draws random numbers until one fits in the given interval. There is some optimization in the code to avoid having too many draws outside the given interval, but since it is only based on bit masking it can happen that many draws are necessary to find a random integer that fits in the given interval. Measures of 50 times slower random number drawing have been measured in this particular kind of random number drawing.

Synopsis

  #include <lyric/Random.hpp>

  class Random
  {
  public:
    ~Random ();
    Random ();
    Random (const Array1D<uint32>& seed);
    Random (uint32 seed);
    Random (const Random& random);
    Random& operator = (const Random& random);
    Size seedsize () const;
    void seed ();
    void seed (const Array1D<uint32>& vals);
    void seed (uint32 val);
    int8  num8  ();
    int16 num16 ();
    int32 num32 ();
    int64 num64 ();
    uint8  unum8 ();
    uint16 unum16 ();
    uint32 unum32 ();
    uint64 unum64 ();
    uint8  unum8  (uint8  maximum);
    uint16 unum16 (uint16 maximum);
    uint32 unum32 (uint32 maximum);
    uint64 unum64 (uint64 maximum);
    uint8  bit ();
    double real ();
    double real (const double& maximum);
    double realx ();
    double realx (const double& maximum);
    double realxx ();
    double realxx (const double& maximum);
  };

Description

˜Random (): Destroys this random number generator, releasing all memory resources.
Random (): Constructs this random number generator, and calls Random::seed() to seed it.
Random (const Array1D<uint32>& seed): Constructs this random number generator, and calls Random::seed(seed) to seed it.
Random (uint32 seed): Constructs this random number generator, and calls Random::seed(seed) to seed it.
Random (const Random& random): Constructs this random number generator from the given random number generator. All properties and data of the given random number generator are copied into this random number generator.
Note that after this construction both random and this will draw the same numbers.
Random& operator = (const Random& random): Assigns this random number generator from the given random number generator. All properties and data of the given random number generator are copied into this random number generator.
Note that after this assignment both random and this will draw the same numbers.
Size seedsize () const: Returns the expected size of the array of seed values given to the Random::seed(vals) function and the Random::Random(seeds) constructor.
void seed (): Seeds or re-seeds this random number generator. This function uses a random device (aka /dev/urandom) if available to read the needed seed bytes. If no random device is available (like on Windows), it uses a hash of the C library time and clock function calls and calls seed(hash), the seed function taking an uint32 argument in this class.
void seed (const Array1D<uint32>& vals): Seeds or re-seeds this random number generator with the given seed values. The given vals array of seed numbers is expected to be of size Random::seedsize(). If the vals array is larger than Random::seedsize(), only the Random::seedsize() first values are taken as seed. If the vals array is smaller than Random::seedsize(), the seed is auto-completed with zeros.
Warning Giving an empty vals seed array results in seeding this random number generator with zeroes. This is probably not what you want. Since LYRIC makes no assumption about what you code, this special seeding is neither controlled, nor replaced with a more sensible seed.
void seed (uint32 val): Seeds or re-seeds this random number generator with the given value. Several magic operations are performed to transform the given value to an array of seeds, but the operations are completely deterministic, and will not produce a very good seed. Better use the Random::seed() function, which will use a random device to to get an array of seeds, or the Random::seed(Array1D<uint32>) seeding function, where an array of seeds can be given. This seeding function is only provided as a C library srand or srandom like function.
int8 num8 (): Returns an 8 bit integer random number in the range [-128,+127].
int16 num16 (): Returns a 16 bit integer random number in the range [-32768,+32767].
int32 num32 (): Returns a 32 bit integer random number in the range [-2147483648,+2147483647].
int64 num64 (): Returns a 64 bit integer random number in the range [-9223372036854775808,+9223372036854775807].
uint8 unum8 (): Returns an 8 bit unsigned integer random number in the range [0,255].
uint16 unum16 (): Returns a 16 bit unsigned integer random number in the range [0,65535].
uint32 unum32 (): Returns a 32 bit unsigned integer random number in the range [0,4294967295].
uint64 unum64 (): Returns a 64 bit unsigned integer random number in the range [0,18446744073709551615].
uint8 unum8 (uint8 maximum): Returns an 8 bit unsigned integer random number in the range [0,maximum].
uint16 unum16 (uint16 maximum): Returns a 16 bit unsigned integer random number in the range [0,maximum].
uint32 unum32 (uint32 maximum): Returns a 32 bit unsigned integer random number in the range [0,maximum].
uint64 unum64 (uint64 maximum): Returns a 64 bit unsigned integer random number in the range [0,maximum].
uint8 bit (): Returns an 8 bit integer random number in the range [0,1]. A simple bit. Can be used as random sign number for example.
double real (): Returns a real random number in the range [0,1].
double real (const double& maximum): Returns a real random number in the range [0,maximum].
double realx (): Returns a real random number in the range [0,1[.
double realx (const double& maximum): Returns a real random number in the range [0,maximum[.
double realxx (): Returns a real random number in the range ]0,1[.
double realxx (const double& maximum): Returns a real random number in the range ]0,maximum[.

Thanks

To Makoto Matsumoto, and Takuji Nishimura for the Mersenne Twister pseudo random number generator. The algorithm’s home page is at http: //www.math.keio.ac.jp/~matumoto/emt.html
To Richard J. Wagner for his C++ implementation of the Mersenne Twister PRNG, on which this implementation is based. Richard’s code can be found at http://www-personal.engin.umich.edu/~wagnerr/MersenneTwister.html

[next] [prev] [prev-tail] [front] [up]