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 #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>
37  class MixMaxEngineImpl;
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 */
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:176
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:175
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:139
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:103
ROOT::Math::MixMaxEngineImpl
Definition: MixMaxEngineImpl.h:50
ROOT::Math::MixMaxEngine::BaseType
TRandomEngine BaseType
Definition: MixMaxEngine.h:107
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:171
TRandomEngine.h
ROOT::Math::MixMaxEngine17
MixMaxEngine< 17, 0 > MixMaxEngine17
Definition: MixMaxEngine.h:177
MixMaxEngine.icc
ROOT::Math::MixMaxEngine::StateInt_t
uint64_t StateInt_t
Definition: MixMaxEngine.h:111
ROOT::Math::MixMaxEngine::Rndm
virtual double Rndm()
Definition: MixMaxEngine.h:136
ROOT
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
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:115