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 < R < 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 < seed < 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 < 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>main23.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<double, double> 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) 2012 Torbjorn Sjostrand --> |
---|