Logo ROOT   6.19/01
Reference Guide
MixMaxEngine.h
Go to the documentation of this file.
1 // @(#)root/mathcore:$Id$
2 // Author: L. Moneta Tue Aug 4 2015
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2015 LCG ROOT Math Team, CERN/PH-SFT *
7  * *
8  * *
9  **********************************************************************/
10 
11 // random engines based on ROOT
12 
13 #ifndef ROOT_Math_MixMaxEngine
14 #define ROOT_Math_MixMaxEngine
15 
16 #include <cstdint>
17 #include <vector>
18 #include <string>
19 
20 #include "Math/TRandomEngine.h"
21 
22 
23 // struct rng_state_st; /// forward declare generator state
24 
25 // typedef struct rng_state_st rng_state_t;
26 
27 // namespace mixmax {
28 // template<int Ndim>
29 // class mixmax_engine;
30 // }
31 
32 namespace ROOT {
33 
34  namespace Math {
35 
36  template<int N>
38 
39 /**
40 MixMaxEngine is a wrapper class for the MIXMAX Random number generator.
41 MIXMAX is a matrix-recursive random number generator introduced by
42 G. Savvidy.
43 
44 The real implementation of the generator, written in C, is in the mixmax.h and mixmax.cxx files.
45 This generator code is available also at hepforge: http://mixmax.hepforge.org
46 The MIXMAX code has been created and developed by Konstantin Savvidy and it is
47 released under GNU Lesser General Public License v3.
48 
49 This wrapper class provides 3 different variants of MIXMAX according to the template para extra parameter N.
50 The extra parameter, `SkipNumber`, is used to perform additional iterations of the generator before returning the random numbers.
51 For example, when `SkipNumber = 2`, the generator will have two extra iterations that will be discarder.
52 
53  - MIXMAX with N = 240. This is a new version of the generator (version 2.0beta) described in the
54  <a href="http://dx.doi.org/10.1016/j.chaos.2016.05.003">2016 paper</a> (3rd reference), with
55  special number \f$s=487013230256099140\f$, \f$m=2^{51}+1\f$ and having a period of \f$10^{4389}\f$.
56 
57  - MIXMAX with N = 17, from the 2.0 beta version with \f$s=0\f$ and \f$m=2^{36}+1\f$. The period of the
58  generator is \f$10^{294}\f$.
59 
60  - MIXMAX with N = 256 from the 1.0 version. The period is (for `SkipNumber=0`) \f$10^{4682}\f$.
61  For this generator we recommend in ROOT using a default value of `SkipNumber=2, while for the
62  previous two generators skipping is not needed.
63 
64 This table describes the properties of the MIXMAX generators. MIXMAX is a genuine 61 bit
65 generator on the Galois field GF[p], where \f$p=2^{61}-1\f$ is the Mersenne prime number.
66 The MIXMAX generators with these parameters pass all of the BigCrush
67 tests in the [TestU01 suite](http://simul.iro.umontreal.ca/testu01/tu01.html)
68 
69 
70 
71 | Dimension | Entropy | Decorrelation Time | Iteration Time | Relaxation Time | Period q |
72 |-----------|-------------|----------------------------------|-----------------|---------------------------------------------------|-------------------------------------|
73 | N | \f$~h(T)\f$ | \f$\tau_0 = {1\over h(T) 2N }\f$ | t | \f$\tau ={1\over h(T) \ln {1\over \delta v_0}}\f$ | \f$\log_{10} (q)\f$ |
74 | 256 | 194 | 0.000012 | 1 | 95.00 | 4682 (full period is not confirmed) |
75 | 8 | 220 | 0.00028 | 1 | 1.54 | 129 |
76 | 17 | 374 | 0.000079 | 1 | 1.92 | 294 |
77 | 240 | 8679 | 0.00000024 | 1 | 1.17 | 4389 |
78 
79 
80 The entropy \f$h(T)\f$, decorrelation time \f$\tau_0\f$ decorrelation time, relaxation
81 time \f$\tau\f$ and period of the MIXMAX generator, expressed in units of the iteration
82 time \f$t\f$, which is normalised to 1. Clearly \f$\tau_0~ < t ~< \tau\f$.
83 
84 #### The References for MIXMAX are:
85 
86  - G.K.Savvidy and N.G.Ter-Arutyunian, *On the Monte Carlo simulation of physical systems,
87  J.Comput.Phys. 97, 566 (1991)*;
88  Preprint EPI-865-16-86, Yerevan, Jan. 1986
89 
90  - K.Savvidy, *The MIXMAX random number generator*,
91  Comp. Phys. Commun. 196 (2015), pp 161–165
92  http://dx.doi.org/10.1016/j.cpc.2015.06.003
93 
94  - K.Savvidy and G.Savvidy, *Spectrum and Entropy of C-systems MIXMAX Random Number Generator*,
95 Chaos, Solitons & Fractals, Volume 91, (2016) pp. 33–38
96 http://dx.doi.org/10.1016/j.chaos.2016.05.003
97 
98 
99 @ingroup Random
100 */
101 
102  template<int N, int SkipNumber>
103  class MixMaxEngine : public TRandomEngine {
104 
105  public:
106 
108 
109  // this should be changed for WINDOWS
110 #ifndef __LP64__
111  typedef uint64_t StateInt_t;
112 #else
113  typedef unsigned long long StateInt_t;
114 #endif
115  typedef uint64_t Result_t;
116 
117 
118  MixMaxEngine(uint64_t seed=1);
119 
120  virtual ~MixMaxEngine();
121 
122 
123  /// Get the size of the generator
124  static int Size();
125 
126  /// maximum integer that can be generated. For MIXMAX is 2^61-1
127  static uint64_t MaxInt();
128 
129  /// minimum integer that can be generated. For MIXMAX is 0
130  static uint64_t MinInt();
131 
132  /// set the generator seed
133  void SetSeed(Result_t seed);
134 
135  // generate a random number (virtual interface)
136  virtual double Rndm() { return Rndm_impl(); }
137 
138  /// generate a double random number (faster interface)
139  inline double operator() () { return Rndm_impl(); }
140 
141  /// generate an array of random numbers
142  void RndmArray (int n, double * array);
143 
144  /// generate a 64 bit integer number
145  Result_t IntRndm();
146 
147  /// get name of the generator
148  static const char *Name();
149 
150  protected:
151  // protected functions used for tesing the generator
152 
153  /// get the state of the generator
154  void GetState(std::vector<StateInt_t> & state) const;
155 
156 
157  ///set the full initial generator state
158  void SetState(const std::vector<StateInt_t> & state);
159 
160  /// Get the counter (between 0 and Size-1)
161  int Counter() const;
162 
163 
164  private:
165 
166  /// implementation function to generate the random number
167  double Rndm_impl();
168 
169  //rng_state_t * fRngState; // mix-max generator state
170  //mixmax::mixmax_engine<N> * fRng; // mixmax internal engine class
171  MixMaxEngineImpl<N> * fRng; // mixmax internal engine class
172 
173  };
174 
178 
179  extern template class MixMaxEngine<240,0>;
180  extern template class MixMaxEngine<256,0>;
181  extern template class MixMaxEngine<256,2>;
182  extern template class MixMaxEngine<256,4>;
183  extern template class MixMaxEngine<17,0>;
184  extern template class MixMaxEngine<17,1>;
185  extern template class MixMaxEngine<17,2>;
186 
187  } // end namespace Math
188 
189 } // end namespace ROOT
190 
191 
192 #include "Math/MixMaxEngine.icc"
193 
194 #endif /* ROOT_Math_MixMaxEngine */
static uint64_t MaxInt()
maximum integer that can be generated. For MIXMAX is 2^61-1
void SetState(const std::vector< StateInt_t > &state)
set the full initial generator state
Namespace for new ROOT classes and functions.
Definition: StringConv.hxx:21
virtual double Rndm()
Definition: MixMaxEngine.h:136
static uint64_t MinInt()
minimum integer that can be generated. For MIXMAX is 0
MixMaxEngine< 256, 2 > MixMaxEngine256
Definition: MixMaxEngine.h:176
MixMaxEngineImpl< N > * fRng
Definition: MixMaxEngine.h:171
static const char * Name()
get name of the generator
MixMaxEngine(uint64_t seed=1)
double Rndm_impl()
implementation function to generate the random number
void SetSeed(Result_t seed)
set the generator seed
void RndmArray(int n, double *array)
generate an array of random numbers
MixMaxEngine is a wrapper class for the MIXMAX Random number generator.
Definition: MixMaxEngine.h:103
int Counter() const
Get the counter (between 0 and Size-1)
double operator()()
generate a double random number (faster interface)
Definition: MixMaxEngine.h:139
static int Size()
Get the size of the generator.
MixMaxEngine< 240, 0 > MixMaxEngine240
Definition: MixMaxEngine.h:175
Result_t IntRndm()
generate a 64 bit integer number
MixMaxEngine< 17, 0 > MixMaxEngine17
Definition: MixMaxEngine.h:177
void GetState(std::vector< StateInt_t > &state) const
get the state of the generator
Namespace for new Math classes and functions.
const Int_t n
Definition: legend1.C:16