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