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:

random values are shooted using static methods

The static generator is a singleton;

random values are shooted using static methods

The user must take care of the engine objects he/she instantiates.

random values are shooted using methods

Doing so, the engine will be associated to the distribution object and the generator mechanism will be by-passed by using the basic

**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:

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 ...The class provides a method

The

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 levelThe engine state can be streamed through ad-hoc defined stream operators << and >>.

**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.

The engine state can be streamed through ad-hoc defined stream operators << and >>.

**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. ...The

The engine state can be streamed through ad-hoc defined stream operators << and >>.

**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!

The static methods

The static method

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"Only one random engine can be active at a time, the user can decide at any time to change it, define a new one (if not done already) and set it:

ex. ... DRand48Engine theNewEngine; HepRandom::setTheEngine(&theNewEngine); ...or simply setting it to an old instantiated engine (the old engine status is kept and the new random sequence will start exactly from the last one previously interrupted):

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

**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 valuesA speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution provided by the engine, by-passing the

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);A speculate set of

An operator () corresponding to the fire() method is provided.

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)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

An operator () using the default mean value is provided.

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)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

An operator () using default mean and deviation is provided.

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)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

An operator () using the plain algorithm and default values is provided.

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)Other static methods are provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

Operators () are provided.

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

Class defining methods for shooting binomial distributed random values, given a sample size

Valid input values satisfy the relation

ex. ... double n,p; ... double num = RandBinomial::shoot(); // (sample=1, prob=1) double num = RandBinomial::shoot(n,p); // (sample=n, prob=p)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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)A speculate set of

Operators () are provided.

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)

Class defining methods for shooting Chi^2 distributed random values, given a number of degrees of freedom a (default=1.0). Default values are used for operator ().

Valid values of

ex. ... double a; ... double num = RandChiSquare::shoot(); // (deg=1) double num = RandChiSquare::shoot(a); // (deg=a)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

Operators () are provided.

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

Class defining methods for shooting gamma distributed random values, given a

Valid input values are

ex. ... double a,lm; ... double num = RandGamma::shoot(); // (k=1, lambda=1) double num = RandGamma::shoot(a,lm); // (k=a, lambda=lm)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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)A speculate set of

Operators () are provided.

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)

Class defining methods for shooting Student's t- distributed random values, given a number of degrees of freedom

Default values are used for operator (). Valid input values are

ex. ... double a; ... double num = RandStudentT::shoot(); // (deg=1) double num = RandStudentT::shoot(a); // (deg=a)A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

Operators () are provided.

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

This class defines methods for shooting generally distributed random values, given a user-defined probability distribution function.

The probability distribution function

- No static methods are provided by this class, since objects of this kind must be explicitly instantiated !

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.A speculate set of static methods is provided to shoot random numbers from given random engines. Using these methods, the user is responsible of the state of the random engine(s) he/she is activating, since these methods act directly on the flat distribution of the engine, by-passing the

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

An Operator () is provided.

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

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: