PYTHIA8/pythia8145/htmldoc/RandomNumbers.html

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