HEP Random

1. Introduction.
2. Classes description.
3. Distribution Classes description & examples.
4. Design Issues.

1. Introduction

The HEP Random module originally part of GEANT4, has been designed and developed starting from the Random class of MC++, the CLHEP's HepRandom module with no persistency and the Rogue Wave approach in Math.h++ package.
The current release consists of 24 classes implementing 12 different random engines and 10 different random distributions.
Each random distribution belongs to a different distribution-class which can collect different algorithms and different calling sequence for each method to define distribution parameters or range-intervals.
Each distribution-class collects also methods to fill arrays of specified size of distributed random values.

There are 3 different ways of shooting random values:

Using the static generator defined in HepRandom:
random values are shooted using static methods shoot() defined for each distribution class. The static generator will use as default engine an HepJamesRandom global object and the user can set its properties or change it with a new instantiated engine object by using the static methods defined in HepRandom.
The static generator is a singleton; createInstance() is the method to invoke to create it.

Skiping the static generator and specifying an engine object:
random values are shooted using static methods shoot(*HepRandomEngine) defined for each distribution class. The user must instantiate an engine object and give it as argument to the shoot method. The generator mechanism will be then by-passed by using the basic flat() method of the specified engine.
The user must take care of the engine objects he/she instantiates.

Skiping the static generator and instantiating a distribution object:
random values are shooted using methods fire() (NOT static) defined for each distribution class. The user must instantiate a distribution object giving as argument to the constructor an engine by pointer or by reference.
Doing so, the engine will be associated to the distribution object and the generator mechanism will be by-passed by using the basic flat() method of that engine. If the engine is passed by pointer the corresponding engine object will be deleted by the distribution's destructor, if passed by reference it will not be deleted by the distribution's destructor.

2. Classes description

HepRandomEngine
Is the abstract class defining the interface for each random engine. It implements the getSeed() and getSeeds() methods which return the initial seed value and the initial array of seeds respectively. It defines 7 pure virtual functions: flat(), flatArray(), setSeed(), setSeeds(), saveStatus(), restoreStatus() and showStatus(), which are implemented by the concrete random engines each one inheriting from this abstract class.
Many concrete random engines can be defined and added to the structure, simply making them inheriting from HepRandomEngine and defining concrete methods for them in such a way that flat() and flatArray() return double random values ranging between ]0,1[.
All the random engines have a default seed value already set. They can however be instantiated with a different seed value set up by the user. The user, whenever necessary, can initialise the engine with a new seed by either using a static method defined in HepRandom, or the methods to set seeds defined in the engine itself.
Methods saveStatus() and restoreStatus() can be used to save to file the current status of an engine and restore it from a previous saved configuration.
The showStatus() method dumps on screen the status of the engine currently in use.
All these methods can be called statically from HepRandom or directly at engine level.

HepJamesRandom
This class implements the algorithm described in "F.James, Comp. Phys. Comm. 60 (1990) 329" for pseudo-random numbers generation.
This is the default random engine for the static generator; it will be invoked by each distribution class unless the user sets a different one.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

DRand48Engine
Random engine using the drand48() and srand48() system functions from C standard library to implement the flat() basic distribution and for setting seeds respectively.
DRand48Engine uses the seed48() function from C standard library to retrieve the current internal status of the generator, which is represented by 3 short values. Copies of an object of this kind are not allowed.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

RandEngine
Simple random engine using the rand() and srand() system functions from C standard library to implement the flat() basic distribution and for setting seeds respectively.
To keep track of the current status of an engine of this kind, a counter is used and its value is stored as data-member. Copies of an object of this kind are not allowed.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

RanluxEngine
The algorithm for RanluxEngine has been taken from the original implementation in FORTRAN77 by Fred James, part of the MATHLIB HEP library.
The initialisation is carried out using a Multiplicative Congruential generator using formula constants of L'Ecuyer as described in "F.James, Comp. Phys. Comm. 60 (1990) 329-344". It provides 5 different luxury levels:

level 0 (p=24): equivalent to the original RCARRY of Marsaglia and Zaman, very long period, but fails many tests.

level 1 (p=48): considerable improvement in quality over level 0, now passes the gap test, but still fails spectral test.

level 2 (p=97): passes all known tests, but theoretically still defective.

level 3 (p=223): DEFAULT value. Any theoretically possible correlations have very small chance of being observed.

level 4 (p=389): highest possible luxury, all 24 bits chaotic.

  ex. ...
     RanluxEngine theRanluxEngine(seed,4);
     // instantiates an engine with "seed" and the best luxury-level
      ... or
     RanluxEngine theRanluxEngine;
     // instatiates an engine with default seed value and luxury-level 3
      ...

  ex. ...
     HepRandom::setTheSeed(seed,4);  // sets the seed to "seed" and luxury
                                     // to 4
     HepRandom::setTheSeed(seed);  // sets the seed to "seed" keeping the
                                   // current luxury level

Ranlux64Engine
The algorithm for this random engine has been taken from the notes of a double-precision ranlux implementation by Martin Luscher, dated November 1997.
This engine has "luxury" levels, determining how many pseudo-random numbers are discarded for every twelve values used. Three levels are given, with the note that Luscher himself advocates only the highest two levels for this engine.

level 0 (p=109): Throw away 109 values for every 12 used

level 1 (p=202): DEFAULT. Throw away 202 values for every 12 used

level 2 (p=397): Throw away 397 values for every 12 used

RanecuEngine
The algorithm for RanecuEngine is taken from the one originally written in FORTRAN77 as part of the MATHLIB HEP library. The initialisation is carried out using a Multiplicative Congruential generator using formula constants of L'Ecuyer as described in "F.James, Comp. Phys. Comm. 60 (1990) 329-344".
Seeds are taken from SeedTable given an index, the getSeed() method returns the current index of SeedTable. The setSeeds() method will set seeds in the local SeedTable at a given position index (if the index number specified exceeds the table's size, (index%size) is taken):

  ex. ...
     int index=n;
     long seeds[2];
     const long* table;
     table = HepRandom::getTheSeeds();
       // it returns a pointer "table" to the local SeedTable at the
       // current "index" position
     ...
     HepRandom::setTheSeeds(seeds,index);
       // sets the new "index" for seeds and modify the values inside
       // the local SeedTable at the "index" position. If the index is
       // not specified, the current index in the table is considered.
     ...

Hurd160Engine
The starting point for the Hurd Random algorithm is the paper in "IEEE Transactions on Computers c23, 2 Feb 1974". The algorithm is essentially a series of 32 interconnected b-bit registers. The basic property is that at each step, bit 1 becomes bit 0, bit 2 the new bit 1, bit b the new bit b-1. This is modified so that the new bit b0 is the old bit b1 XOR'd with some bit b-d from the previous bit register. The values of d can be chosen so as to generate a primitive polynomial, a maximal length sequence through all bit patterns except the zero pattern.
This engine uses values based upon Table I of the afore mentioned paper, such that we have 160 total bits, representing 32 5-bit registers (actually implemented as an array of 5 32-bit words).
The engine state can also be streamed through ad-hoc defined stream operators << and >>.

Hurd288Engine
The algorithm adopted for this engine is essentially the same as for Hurd160Engine, except that it acts over a number of 288 total bits, representing 32 9-bit registers (actually implemented as an array of 9 32-bit words).
The engine state can be streamed through ad-hoc defined stream operators << and >>.

MTwistEngine
The algorithm for this random engine is based on the article by M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator", to appear in ACM Trans. on Modeling and Computer Simulation.
It is a twisted GFSR generator with a Mersenne-prime period of 2^19937-1, uniform on open interval (0,1).
For further information, see www.math.keio.ac.jp/~matumoto/emt.html.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

RanshiEngine
The algorithm for this random engine was taken from "F.Gutbrod, Comp. Phys. Comm. 87 (1995) 291-306".
As figurative explanation of the algorithm, imagine a physical system as follows: 512 "black balls" each with their own unique spin, and positions characterized by discrete angles, where the spin is a 32-bit unsigned integer. A "red ball" collides based upon the angle determined by the last 8 bits of its spin, and the spin of the colliding ball is taken as the output random number. The spin of the colliding ball is replaced then with the left circular shift of the black ball's spin XOR'd with the red ball's spin. The black ball's old spin becomes the red ball's.
To avoid the traps presented, two measures are taken: first, the red ball will oscillate between hitting the lower half of the buffer on one turn and the upper half on another; second, the red ball's spin is incremented by a counter of the number of random numbers produced.
The result is scaled to a double precision floating point number to which is added another random double further scaled 2^(53-32) places to the right in order to ensure that the remaining bits of the result are not left empty due to the mere 32 bits representation used internally.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

DualRand Engine
This is a 32-bit C++ implementation of the Canopy random number generator DualRand: exclusive-or of a feedback shift register and integer congruence random number generator.
The feedback shift register uses offsets 127 and 97. The integer congruence generator uses a different multiplier for each stream. The multipliers are chosen to give full period and maximum potency for modulo 2^32. The period of the combined random number generator is 2^159 - 2^32, and the sequences are different for each stream (not just started in a different place).
The engine state can be streamed through ad-hoc defined stream operators << and >>.

TripleRand Engine
TripleRand is canopy pseudo-random number generator. It uses the Tausworthe exclusive-or shift register, a simple Integer Coungruence generator, and the Hurd 288 total bit shift register, all XOR'd with each other.
It behavies similarly to DualRand, with the addition of the Hurd288Engine. In addition to DualRand, this generator is amended to also add in the exclusive or of the 288-total bit Hurd engine which in this case is a series of 32 interconnected 9-bit shift registers, with the newest bit of each register formed by the XOR of the previous bit and some bit b-d from a previous register, where d is chosen to create a primitive polynomial to maximize the period.
The engine state can be streamed through ad-hoc defined stream operators << and >>.

HepRandom
This is a singleton class, instantiated by default within the HEP Random module and using an HepJamesRandom engine as default algorithm for pseudo-random number generation.

However, on some compilers the static instance of the HepRandom generator needs to be created explicitly in the client code. The static generator is assured to be correctly initialized by including the Randomize.h header in the client code, or by invoking explicitly the HepRandom::createInstance() static function before any usage of the Random classes.

  ex.
      HepRandom::createInstance();  // to force instantiation of static generator
                                    // before any usage of HepRandom classes!

  ex.  ...
      HepRandom::setTheSeed(seed);  // to change the current seed to 'seed'
      int startSeed = HepRandom::getTheSeed();  // to get the current
       ...                                      // initial seed
      HepRandom::saveEngineStatus();    // to save the current engine status
                                        // on file.
      HepRandom::restoreEngineStatus(); // to restore the current engine to
                                        // a previous saved configuration.
      HepRandom::showEngineStatus();    // to display the current engine
                                        // status to the std output.
      ...
      int index=n;
      long seeds[2];
      HepRandom::getTheTableSeeds(seeds,index);
        // fills "seeds" with the values stored in the global seedTable
        // at position "index"

  ex.  ...
      DRand48Engine theNewEngine;
      HepRandom::setTheEngine(&theNewEngine);
       ...

  ex.  ...
      HepRandom::setTheEngine(&myOldEngine);

3. Distribution Classes description & examples

RandFlat
Distribution-class defining methods for shooting flat random numbers, double or integers. It provides also methods to fill with double flat values arrays of specified size.

  ex.  ...
      double m,n;
      ...
      double fnum = RandFlat::shoot();         // fnum  ]0,1[
      double fnum = RandFlat::shoot(n);        // fnum  ]0,n[
      double fnum = RandFlat::shoot(-m,n);     // fnum  ]-m,n[
      long h,k;
      ...
      long inum = RandFlat::shootInt(k);       // inum  [0,k[
      long inum = RandFlat::shootInt(-h,k);    // inum  [-h,k[
      ...
      int i = RandFlat::shootBit();     // it returns just a bit (0 or 1)
      ...                               // of a random number
      const int size=n;
      double vect[size];
      RandFlat::shootArray(size,vect);  // to fill an array "vect" of n
                                        // double flat values

  ex.  ...
      RanecuEngine theRanecuEngine;
      double m,n;
      ...
      double fnum = RandFlat::shoot(&theRanecuEngine);      // fnum  ]0,1[
      double fnum = RandFlat::shoot(&theRanecuEngine,n);    // fnum  ]0,n[
      double fnum = RandFlat::shoot(&theRanecuEngine,-m,n); // fnum  ]-m,n[
      long h,k;
      ...
      long inum = RandFlat::shootInt(&theRanecuEngine,k);     // inum  [0,k[
      long inum = RandFlat::shootInt(&theRanecuEngine,-h,k); // inum  [-h,k[
       ...
      int i = RandFlat::shootBit(&theRanecuEngine); // it returns just a bit
      ...                                           // of a random number
      const int size=n;                       // to fill an array "vect"
      double vect[size];                      // of n double flat values
      RandFlat::shootArray(&theRanecuEngine,size,vect);

  ex.  ...
      RanecuEngine aRanecuEngine;
      RandFlat FlatDist(aRanecuEngine);
      double m,n;
      ...
      double fnum = FlatDist.fire();        // fnum  ]0,1[
      double fnum = FlatDist.fire(n);       // fnum  ]0,n[
      double fnum = FlatDist.fire(-m,n);    // fnum  ]-m,n[
      long h,k;
      ...
      long inum = FlatDist.fireInt(k);      // inum  [0,k[
      long inum = FlatDist.fireInt(-h,k);   // inum  [-h,k[
      ...
      int i = FlatDist.fireBit();       // it returns just a bit (0 or 1)
      ...                               // of a random number
      const int size=n;                     // to fill an array "vect"
      double vect[size];                    // of n double flat values
      FlatDist.fireArray(size,vect);

  ex.  ...
      double m;
      ...
      double num = RandExponential::shoot();   // (mean=1)
      double num = RandExponential::shoot(m);  // (mean=m)

  ex.  ...
      RanluxEngine theRanluxEngine(19780503,4);
      double m;
      ...
      double num = RandExponential::shoot(&theRanluxEngine);   // (mean=1)
      double num = RandExponential::shoot(&theRanluxEngine,m); // (mean=m)

  ex.  ...
      RanluxEngine aRanluxEngine(19780503,4);
      RandExponential ExpDist(aRanluxEngine);
      double m;
      ...
      double num = ExpDist.fire();   // (mean=1)
      double num = ExpDist.fire(m);  // (mean=m)

  ex.  ...
      double m,s;
      ...
      double num = RandGauss::shoot();     // (mean=0)
      double num = RandGauss::shoot(m,s);  // (mean=m, stDev=s)

  ex.  ...
      RandEngine theRandEngine;
      double m,s;
      ...
      double num = RandGauss::shoot(&theRandEngine);
      double num = RandGauss::shoot(&theRandEngine,m,s);

  ex.  ...
      RandEngine aRandEngine;
      RandGauss GaussDist(aRandEngine);
      double m,s;
      ...
      double num = GaussDist.fire();
      double num = GaussDist.fire(m,s);

  ex.  ...
    double m,g,c;
    ...
    double num = RandBreitWigner::shoot(m,g);   // (mean=m, gamma=g)
    double num = RandBreitWigner::shoot(m,g,c); // (mean=m, gamma=g, cut=c)

  ex.  ...
    double m,g,c;
    DRand48Engine theDRand48Engine;
    ...
    double num = RandBreitWigner::shoot(&theDRand48Engine,m,g);
    double num = RandBreitWigner::shoot(&theDRand48Engine,m,g,c);

  ex.  ...
    double m,g,c;
    DRand48Engine aDRand48Engine;
    RandBreitWigner BWDist(aDRand48Engine);
    ...
    double num = BWDist.fire(m,g);
    double num = BWDist.fire(m,g,c);

  ex.  ...
      double m;
      ...
      long num = RandPoisson::shoot(m);  // (mean=m)

  ex.  ...
      RanecuEngine theRanecuEngine;
      double m;
      ...
      long num = RandPoisson::shoot(&theRanecuEngine,m);  // (mean=m)

  ex.  ...
      RanecuEngine aRanecuEngine;
      RandPoisson PoissonDist(aRanecuEngine);
      double m;
      ...
      long num = PoissonDist.fire(m);  // (mean=m)

  ex.  ...
      double n,p;
      ...
      double num = RandBinomial::shoot();        // (sample=1, prob=1)
      double num = RandBinomial::shoot(n,p);     // (sample=n, prob=p)

  ex.  ...
      RanshiEngine theRanshiEngine;
      double n,p;
      ...
      double num =
        RandBinomial::shoot(&theRanshiEngine);     // (sample=1, prob=1)
      double num =
        RandBinomial::shoot(&theRanshiEngine,n,p); // (sample=n, prob=p)

  ex.  ...
      Hurd160Engine aHurd160Engine;
      RandBinomial BinDist(aHurd160Engine);
      double n,p;
      ...
      double num = BinDist.fire();     // (sample=1, prob=1)
      double num = BinDist.fire(n,p);  // (sample=n, prob=p)

  ex.  ...
      double a;
      ...
      double num = RandChiSquare::shoot();        // (deg=1)
      double num = RandChiSquare::shoot(a);       // (deg=a)

  ex.  ...
      DualRand theDualRandEngine;
      double a;
      ...
      double num =
        RandChiSquare::shoot(&theDualRandEngine);   // (deg=1)
      double num =
        RandChisquare::shoot(&theDualRandEngine,a); // (deg=a)

  ex.  ...
      Hurd288Engine aHurd288Engine;
      RandChiSquare Chi2Dist(aHurd288Engine);
      double a;
      ...
      double num = Chi2Dist.fire();   // (deg=1)
      double num = Chi2Dist.fire(a);  // (deg=a)

  ex.  ...
      double a,lm;
      ...
      double num = RandGamma::shoot();        // (k=1, lambda=1)
      double num = RandGamma::shoot(a,lm);    // (k=a, lambda=lm)

  ex.  ...
      MTwistEngine theMTwistEngine;
      double a,lm;
      ...
      double num =
        RandGamma::shoot(&theMTwistEngine);      // (k=1, lambda=1)
      double num =
        RandGamma::shoot(&theMTwistEngine,a,lm); // (k=a, lambda=lm)

  ex.  ...
      Ranlux64Engine aRanlux64Engine;
      RandGamma GammaDist(aRanlux64Engine);
      double a,lm;
      ...
      double num = GammaDist.fire();      // (k=1, lambda=1)
      double num = GammaDist.fire(a,lm);  // (k=a, lambda=lm)

  ex.  ...
      double a;
      ...
      double num = RandStudentT::shoot();        // (deg=1)
      double num = RandStudentT::shoot(a);       // (deg=a)

  ex.  ...
      TripleRand theTripleRandEngine;
      double a;
      ...
      double num =
        RandStudentT::shoot(&theTripleRandEngine);   // (deg=1)
      double num =
        RandStudentT::shoot(&theTripleRandEngine,a); // (deg=a)

  ex.  ...
      RandEngine aRandEngine;
      RandChiSquare StudDist(aRandEngine);
      double a;
      ...
      double num = StudDist.fire();   // (deg=1)
      double num = StudDist.fire(a);  // (deg=a)

  ex.  ...
      double* probList;
      int nBins;
      ...
      RandGeneral GenDist(probList,nBins);
      double num = GenDist.shoot();  // shoots values using the engine
                                     // in the static generator. shoot()
                                     // provides the same functionality
                                     // of fire() in this case.

  ex.  ...
      RanecuEngine aRanecuEngine;
      double* probList;
      int nBins;
      ...
      RandGeneral GenDist(probList,nBins);
      double num = GenDist.shoot(&aRanecuEngine);   // shoots values using the
                                                    // specified engine

  ex.  ...
      RanluxEngine aRanluxEngine;
      double* probList;
      int nBins;
      ...
      RandGeneral GenDist(aRanluxEngine,probList,nBins);
      ...
      double num = GenDist.fire();  // shoots values using the specified
                                    // engine local to the distribution

4. Design Issues

The use of a static generator has been introduced in the original design of HEP Random as a project requirement in Geant4. In applications like Geant4, where it is necessary to shoot random numbers (normally of the same engine) in many different methods and parts of the program, it is highly desirable not to have to rely-on/know global objects instantiated. By using static methods via a unique generator, randomness of a sequence of numbers is best assured.

Analysis and design of the HEP Random module have been achieved following the Booch Object-Oriented methodology.
Here follows a list of diagrams describing the model according to the Booch notation:

Class Diagram

Object Diagram: shooting via the generator

Object Diagram: shooting via distribution objects

Object Diagram: shooting with arbitrary engines

Interaction Diagram: shooting via the generator

Interaction Diagram: shooting via distribution objects

Interaction Diagram: shooting with arbitrary engines

Class Specifications