PYTHIA8/pythia8145/xmldoc/RandomNumbers.xml

   1 <chapter name="Random Numbers">
   2
   3 <h2>Random Numbers</h2>
   4
   5 This page describes the random-number generator in PYTHIA and
   6 how it can be replaced by an external one.
   7
   8 <h3>Internal random numbers</h3>
   9
  10 The <code>Rndm</code> class generates random numbers, using the
  11 Marsaglia-Zaman-Tsang algorithm <ref>Mar90</ref>.
  12
  13 <p/>
  14 Random numbers <code>R</code> uniformly distributed in
  15 <code>0 &lt; R &lt; 1</code> are obtained with
  16 <pre>
  17    Rndm::flat();
  18 </pre>
  19 There are also methods to generate according to an exponential, to
  20 <ei>x * exp(-x)</ei>, to a Gaussian, or picked among a set of
  21 possibilites, which make use of <code>flat()</code>.
  22
  23 <p/>
  24 If the random number generator is not initialized before, it will be
  25 so the first time it is asked to generate a random number, and then
  26 with the default seed, 19780503. This means that, by default, all runs
  27 will use identically the same random number sequence. This is
  28 convenient for debugging purposes, but dangerous if you intend to
  29 run several "identical" jobs to boost statistics. You can initialize,
  30 or reinitialize, with your own choice of seed with a
  31 <pre>
  32    Rndm::init(seed);
  33 </pre>
  34 Here values <code>0 &lt; seed &lt; 900 000 000</code> gives so many
  35 different random number sequences, while <code>seed = 0</code> will call
  36 the <code>Stdlib time(0)</code> function to provide a "random"
  37 <code>seed</code>, and <code>seed &lt; 0</code> will revert back to
  38 the default <code>seed</code>.
  39
  40 <p/>
  41 The <code>Pythia</code> class defines <aloc href="RandomNumberSeed">a
  42 flag and a mode</aloc>, that allows the <code>seed</code> to be set in
  43 the <code>Pythia::init</code> call. That would be the standard way for a
  44 user to pick the random number sequence in a run.
  45
  46 <h3>External random numbers</h3>
  47
  48 <code>RndmEngine</code> is a base class for the external handling of
  49 random-number generation. The user-written derived class is called
  50 if a pointer to it has been handed in with the
  51 <code>pythia.rndmEnginePtr()</code> method. Since the default
  52 Marsaglia-Zaman-Tsang algorithm is quite good, chances are that any
  53 replacement would be a step down, but this may still be required by
  54 consistency with other program elements in big experimental frameworks.
  55
  56 <p/>
  57 There is only one pure virtual method in <code>RndmEngine</code>, to
  58 generate one random number flat in the range between 0 and 1:
  59 <pre>
  60   virtual double flat() = 0;
  61 </pre>
  62 Note that methods for initialization are not provided in the base
  63 class, in part since input parameters may be specific to the generator
  64 used, in part since initialization can as well be taken care of
  65 externally to the <code>Pythia</code> code.
  66
  67 <p/>
  68 An example illustrating how to run with an external random number
  69 generator is provided in <code>main24.cc</code>.
  70
  71 <h3>The methods</h3>
  72
  73 We here collect a more complete and formal overview of the methods.
  74
  75 <method name="Rndm::Rndm()">
  76 construct a random number generator, but does not initialize it.
  77 </method>
  78
  79 <method name="Rndm::Rndm(int seed)">
  80 construct a random number generator, and initialize it for the
  81 given seed number.
  82 </method>
  83
  84 <method name="bool Rndm::rndmEnginePtr( RndmEngine* rndmPtr)">
  85 pass in pointer for external random number generation.
  86 </method>
  87
  88 <method name="void Rndm::init(int seed = 0)">
  89 initialize, or reinitialize, the random number generator for the given
  90 seed number. Not necessary if the seed was already set in the constructor.
  91 </method>
  92
  93 <method name="double Rndm::flat()">
  94 generate next random number uniformly between 0 and 1.
  95 </method>
  96
  97 <method name="double Rndm::exp()">
  98 generate random numbers according to <ei>exp(-x)</ei>.
  99 </method>
 100
 101 <method name="double Rndm::xexp()">
 102 generate random numbers according to <ei>x exp(-x)</ei>.
 103 </method>
 104
 105 <method name="double Rndm::gauss()">
 106 generate random numbers according to <ei>exp(-x^2/2)</ei>.
 107 </method>
 108
 109 <method name="pair&lt;double, double&gt; Rndm::gauss2()">
 110 generate a pair of random numbers according to
 111 <ei>exp( -(x^2 + y^2) / 2)</ei>. Is faster than two calls
 112 to <code>gauss()</code>.
 113 </method>
 114
 115 <method name="int Rndm::pick(const vector<double>& prob)">
 116 pick one option among vector of (positive) probabilities.
 117 </method>
 118
 119 <method name="bool Rndm::dumpState(string fileName)">
 120 save the current state of the random number generator to a binary
 121 file. This involves two integers and 100 double-precision numbers.
 122 Intended for debug purposes. Note that binary files may be
 123 platform-dependent and thus not transportable.
 124 </method>
 125
 126 <method name="bool Rndm::readState(string fileName)">
 127 set the state of the random number generator by reading in a binary
 128 file saved by the above command. Comments as above.
 129 </method>
 130
 131 <method name="virtual double RndmEngine::flat()">
 132 if you want to construct an external random number generator
 133 (or generator interface) then you must implement this method
 134 in your class derived from the <code>RndmEningen</code> base class,
 135 to give a random number between 0 and 1.
 136 </method>
 137
 138 </chapter>
 139
 140 <!-- Copyright (C) 2010 Torbjorn Sjostrand -->