Random Numbers

This page describes the random-number generator in PYTHIA and how it can be replaced by an external one.

Internal random numbers

The Rndm class generates random numbers, using the Marsaglia-Zaman-Tsang algorithm [Mar90].

Random numbers R uniformly distributed in 0 < R < 1 are obtained with

 
   Rndm::flat(); 
There are also methods to generate according to an exponential, to x * exp(-x), to a Gaussian, or picked among a set of possibilities, which make use of flat().

If the random number generator is not initialized before, it will be so the first time it is asked to generate a random number, and then with the default seed, 19780503. This means that, by default, all runs will use identically the same random number sequence. This is convenient for debugging purposes, but dangerous if you intend to run several "identical" jobs to boost statistics. You can initialize, or reinitialize, with your own choice of seed with a

 
   Rndm::init(seed); 
Here values 0 < seed < 900 000 000 gives so many different random number sequences, while seed = 0 will call the Stdlib time(0) function to provide a "random" seed, and seed < 0 will revert back to the default seed.

The Pythia class defines a flag and a mode, that allows the seed to be set in the Pythia::init call. That would be the standard way for a user to pick the random number sequence in a run.

External random numbers

RndmEngine is a base class for the external handling of random-number generation. The user-written derived class is called if a pointer to it has been handed in with the pythia.rndmEnginePtr() method. Since the default Marsaglia-Zaman-Tsang algorithm is quite good, chances are that any replacement would be a step down, but this may still be required by consistency with other program elements in big experimental frameworks.

There is only one pure virtual method in RndmEngine, to generate one random number flat in the range between 0 and 1:

 
  virtual double flat() = 0; 
Note that methods for initialization are not provided in the base class, in part since input parameters may be specific to the generator used, in part since initialization can as well be taken care of externally to the Pythia code.

An example illustrating how to run with an external random number generator is provided in main23.cc.

The methods

We here collect a more complete and formal overview of the methods.

Rndm::Rndm()  
construct a random number generator, but does not initialize it.

Rndm::Rndm(int seed)  
construct a random number generator, and initialize it for the given seed number.

bool Rndm::rndmEnginePtr( RndmEngine* rndmPtr)  
pass in pointer for external random number generation.

void Rndm::init(int seed = 0)  
initialize, or reinitialize, the random number generator for the given seed number. Not necessary if the seed was already set in the constructor.

double Rndm::flat()  
generate next random number uniformly between 0 and 1.

double Rndm::exp()  
generate random numbers according to exp(-x).

double Rndm::xexp()  
generate random numbers according to x exp(-x).

double Rndm::gauss()  
generate random numbers according to exp(-x^2/2).

pair<double, double> Rndm::gauss2()  
generate a pair of random numbers according to exp( -(x^2 + y^2) / 2). Is faster than two calls to gauss().

int Rndm::pick(const vector<double>& prob)  
pick one option among vector of (positive) probabilities.

bool Rndm::dumpState(string fileName)  
save the current state of the random number generator to a binary file. This involves two integers and 100 double-precision numbers. Intended for debug purposes. Note that binary files may be platform-dependent and thus not transportable.

bool Rndm::readState(string fileName)  
set the state of the random number generator by reading in a binary file saved by the above command. Comments as above.

virtual double RndmEngine::flat()  
if you want to construct an external random number generator (or generator interface) then you must implement this method in your class derived from the RndmEningen base class, to give a random number between 0 and 1.