From a1c8479f0edf3209831aa70c0c2c5e1822c4b93b Mon Sep 17 00:00:00 2001
From: moneta <lorenzo.moneta@cern.ch>
Date: Tue, 4 Dec 2018 23:07:30 +0100
Subject: [PATCH] update documentation for TRandom
---
math/mathcore/src/TRandom.cxx | 69 +++++++++++++++++++----------------
1 file changed, 38 insertions(+), 31 deletions(-)
diff --git a/math/mathcore/src/TRandom.cxx b/math/mathcore/src/TRandom.cxx
index cee6d3f83a3..6e476635e2e 100644
--- a/math/mathcore/src/TRandom.cxx
+++ b/math/mathcore/src/TRandom.cxx
@@ -16,49 +16,56 @@
@ingroup Random
This is the base class for the ROOT Random number generators.
-This class defines the ROOT Random number interface and it should not be instantiated directly but used via its derived classes
-The derived class are :
+This class defines the ROOT Random number interface and it should not be instantiated directly but used via its derived classes.
+The generator provided in TRandom itself is a LCG (Linear Congruential Generator), the <a href="https://www.gnu.org/software/gsl/manual/html_node/Unix-random-number-generators.html">BSD `rand`
+generator</a>, that it should not be used because its period is only 2**31, i.e. approximatly 2 billion events, that can be generated in just few seconds.
+
+To generate random numbers, one should use the derived class, which are :
+- TRandom3: it is based on the "Mersenne Twister generator",
+it is fast and a very long period of about \f$10^{6000}\f$. However it fails some of the most stringent tests of the
+<a href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01 suite</a>.
+In addition this generator provide only numbers with 32 random bits, which might be not sufficient for some application based on double or extended precision.
+This generator is however used in ROOT used to instantiate the global pointer to the ROOT generator, *gRandom*.
+- ::TRandomMixMax: Generator based on the family of the MIXMAX matrix generators (see the <a href="https://mixmax.hepforge.org">MIXMAX HEPFORGE Web page</a> and the
+ the documentation of the class ROOT::Math::MixMaxEngine for more information), that are base on the Asanov dynamical C systems.
+This generator has a state of N=240 64 bit integers, proof random properties, it provides 61 random bits and it has a very large period (\f$10^{4839}\f$).
+Furthermore, it provides the capability to be seeded with the guarantee that, for each given different seed, a different sequence of random numbers will be generated.
+The only drawback is that the seeding time is time consuming, of the order of 0.1 ms, while the time to generate a number is few ns (more than 10000 faster).
+- ::TRandomMixMax17: Another MixMax generator, but with a smaller state, N=17, and this results in a smaller entropy than the generator with N=240. However, it has the same seeding capabilities, with a much faster seeding time (about 200 times less than TRandomMixMax240 and comparable to TRandom3).
+- ::TRandomMixMax256 : A variant of the MIXMAX generators, based on a state of N=256, and described in the
+ <a href="http://arxiv.org/abs/1403.5355">2015 paper</a>. This implementation has been modified with respect to the paper, by skipping 2 internal interations,
+ to provide improved random properties.
+- TRandomMT64 : Generator based on a the Mersenne-Twister generator with 64 bits,
+ using the implementation provided by the standard library ( <a href="http://www.cplusplus.com/reference/random/mt19937_64/">std::mt19937_64</a> )
- TRandom1 based on the RANLUX algorithm, has mathematically proven random proprieties
- and a period of about 10**171. It is however slower than the others.
+ and a period of about \f$10{171}\f$. It is however much slower than the others and it has only 24 random bits. It can be constructed with different luxury levels.
+- TRandomRanlux48 : Generator based on a the RanLux generator with 48 bits and highest luxury level
+ using the implementation provided by the standard library (<a href="http://www.cplusplus.com/reference/random/ranlux48/">std::ranlux48</a>). The drawback of this generator is its slow generation
+ time.
- TRandom2 is based on the Tausworthe generator of L'Ecuyer, and it has the advantage
-of being fast and using only 3 words (of 32 bits) for the state. The period is 10**26.
-- TRandom3 is based on the "Mersenne Twister generator", and is currently the recommended one,
-since it has quite good random proprieties (period of about 10**6000 ) and it is fast. However it
-fails some of the tests of the TestU)1 suite. In addition this generator provide only random number with
-32 bits random.
-- Generator based on the template TRandomGen<Engine> class. Convenient typedef's, available also at the ROOT prompts, are
- defined for generator of the MIXMAX family (see the <a href="https://mixmax.hepforge.org">MIXMAX HEPFORGE Web page</a>) and based on ROOT::Math::MixMaxEngine,
- and for the random engines from the standard library, based on ROOT::Math::StdEngine
-(see the C++ <a href="http://www.cplusplus.com/reference/random/">random</a> documentation.).
- The typdefs are:
- - ::TRandomMixMax : MIXMAX generator based on a state of N=240. This generator provides 61 bits random with a very large period (10**4839)
- - ::TRandomMixMax17 : MIXMAX generator based on a state of N=17. This generator has a fast seeding time
- compared to N=240, but still a very large period (10**294)
- - ::TRandomMixMax256 : MIXMAX generator based on a state of N=256. It is the generator described in the
- <a href="http://arxiv.org/abs/1403.5355">2015 paper</a>
- (based on a matrix with m=0 and special number s=-1), but with skipping to have higher randomness.
- - ::TRandomMT64 : Generator based on a the Mersenne-Twister generator with 64 bits,
- using the implementation provided by the standard library ( <a href="http://www.cplusplus.com/reference/random/mt19937_64/">std::mt19937_64</a> )
- - ::TRandomRanlux48 : Generator based on a the RanLux generator with 48 bits,
- using the implementation provided by the standard library (<a href="http://www.cplusplus.com/reference/random/ranlux48/">std::ranlux48</a>).
+of being fast and using only 3 words (of 32 bits) for the state. The period however is not impressively long, it is 10**26.
+
+Using the template TRandomGen class (template on the contained Engine type), it is possible to add any generator based on the standard C++ random library
+(see the C++ <a href="http://www.cplusplus.com/reference/random/">random</a> documentation.) or different variants of the MIXMAX generator using the
+ROOT::Math::MixMaxEngine. Some of the listed generator above (e.g. TRandomMixMax256 or TRandomMT64) are convenient typedef's of generator built using the
+template TRandomGen class.
-Note also that this class implements also a very simple generator (linear congruential) with periodicity = 10**9
-which is known to have defects (the lower random bits are correlated)
-and therefore should NOT be used in any statistical study.
+Please note also that this class (TRandom) implements also a very simple generator (linear congruential) with period = \f$10^9\f$, known to have defects (the lower random bits are correlated) and it
+is failing the majority of the random number generator tests. Therefore it should NOT be used in any statistical study.
The following table shows some timings (in nanoseconds/call)
-for the random numbers obtained using a 2.6 GHz Intel Core i7 CPU:
+for the random numbers obtained using a macbookpro 2.6 GHz Intel Core i7 CPU:
- TRandom 3 ns/call (but this is a very BAD Generator, not to be used)
-- TRandom1 82 ns/call
-- TRandom2 7 ns/call
+- TRandom2 5 ns/call
- TRandom3 5 ns/call
- ::TRandomMixMax 6 ns/call
- ::TRandomMixMax17 6 ns/call
-- ::TRandomMixMax256 10 ns/call
- ::TRandomMT64 9 ns/call
-- ::TRandomRanlux48 270 ns/call
+- ::TRandomMixMax256 10 ns/call
+- ::TRandom1 80 ns/call
+- ::TRandomRanlux48 250 ns/call
The following methods are provided to generate random numbers disctributed according to some basic distributions:
--
GitLab