Merge pull request #304 from schmouk/release-2-1

Release 2-1

Author: schmouk

README.md

@@ -1206,3 +1206,13 @@ In ACM Transactions on Mathematical Software, Volume 44, Issue 3, April 2018, Ar
 Also published in arXiv, March 2022 (11 pages)  
 Last reference: arXiv:1505.06582v6 [cs.DS] 20 Nov 2017, see [https://arxiv.org/pdf/1505.06582](https://arxiv.org/pdf/1505.06582).  
 DOI: https://doi.org/10.1145/3159444, https://doi.org/10.48550/arXiv.1505.06582
+
+
+**[12]** Marsaglia, G. 1972.  
+*The structure of linear congruential sequences.*  
+In Applications of Number Theory to Numerical Analysis, S. K. Zaremba, Ed. Academic Press, 249–285.
+
+
+**[13]** Brown, F. B. and Nagaya, Y. 2002.  
+*The MCNP5 random number generator.*  
+Tech. rep. LA-UR-02-3782, Los Alamos National Laboratory

c++11/baseclasses/basemrg31.h

@@ -53,9 +53,11 @@ SOFTWARE.
 *
 *   See Mrg287 for  a  short  period  MR-Generator  (2^287,  i.e. 2.49e+86)  with  low
 *   computation time but 256 integers memory consumption (2^32 modulus calculations).
+* 
 *   See Mrg1457 for a longer period MR-Generator  (2^1457,  i.e. 4.0e+438)  and longer
 *   computation  time  (2^31-1 modulus calculations) but less memory space consumption
 *   (i.e. 47 integers).
+* 
 *   See Mrg49507 for  a  far  longer  period  (2^49_507,  i.e. 1.2e+14_903)  with  low
 *   computation  time  too  (31-bits  modulus)  but  use  of  more memory space (1_597
 *   integers).

c++11/baseclasses/basemrg32.h

@@ -53,9 +53,11 @@ SOFTWARE.
 *
 *   See Mrg287 for  a  short  period  MR-Generator  (2^287,  i.e. 2.49e+86)  with  low
 *   computation time but 256 integers memory consumption (2^32 modulus calculations).
+* 
 *   See Mrg1457 for a longer period MR-Generator  (2^1457,  i.e. 4.0e+438)  and longer
 *   computation  time  (2^31-1 modulus calculations) but less memory space consumption
 *   (i.e. 47 integers).
+* 
 *   See Mrg49507 for  a  far  longer  period  (2^49_507,  i.e. 1.2e+14_903)  with  low
 *   computation  time  too  (31-bits  modulus)  but  use  of  more memory space (1_597
 *   integers).

c++11/baseclasses/basepcg.h

@@ -38,10 +38,10 @@ SOFTWARE.
 *
 *      x(i) = (a*x(i-1) + c) mod m
 *
-*   PCGs associate to this recurrence a permutation of a subpart o f the  bits 
-*   of  the internal state of the PRNG.  The output of PCGs is this permutated
-*   subpart of its internal state,  leading to a very large enhancement of the
-*   randomness of these algorithms compared with the LCGs one.
+*   PCGs associate to this recurrence a permutation  of  a  subpart  of  their
+*   internal state bits.  The output of PCGs is this permutated subpart of its
+*   internal state,  leading to a very large enhancement of the randomness  of
+*   these algorithms compared with the LCGs one.
 *
 *   These PRNGs have been tested with TestU01 by the authors and have shown to 
 *   pass  all  tests  (about  TestU01,  see Pierre L'Ecuyer and Richard Simard 

c++11/baseclasses/baserandom.h

@@ -43,28 +43,70 @@ SOFTWARE.
 //===========================================================================
 /** @brief This is the base class for all pseudo-random numbers generators.
 *
-*   See FastRand32 for a 2^32 (i.e. 4.3e+9) period LC-Generator and  FastRand63  for a
-*   2^63 (i.e. about 9.2e+18) period LC-Generator with low computation time.
+*   See Cwg64 for a minimum 2^70 (i.e. about 1.18e+21) period  Collatz-Weyl  Generator
+*   with  low  computation time,  medium period,  64- bits output values and very good
+*   randomness characteristics.
+*   See Cwg128_64 for a minimum 2^71 (i.e. about 2.36e+21) period C-W  Generator  with
+*   with  very  low  computation time,  medium period,  64-bits output values and very
+*   good randomness characteristics.
+*   See Cwg128 for a minimum 2^135  (i.e. about 4.36e+40)  period  C-W generator  with
+*   very  low  computation time,  medium period,  64- bits output values and very good
+*   randomness characteristics.
 *
-*   See FastRand63 for a 2^63  (i.e.  about  9.2e+18)  period  LC-Generator  with  low
-*   computation  time also,  longer period and quite better randomness characteristics 
-*   than for FastRand32.
+*   See FastRand32 for a 2^32 (i.e. 4.29e+9) period Linear Congruential Generator  and
+*   FastRand63  for  a  2^63  (i.e. about 9.2e+18)  period  LC-Generator with very low
+*   computation time and very low memory consumption (resp. 1 and 2 32-bits integers).
 *
-*   See MRGRand287, MRGRand1457 and MRGRand49507 for long periods MR-Generators (resp.
-*   2^287,  2^1,457  and  2^49,507,  i.e. 2.49e+86, 4.0e+438 and 1.2e+14,903) with low
-*   computation time but resp. 256, 47 and 1,597 integers memory  consumption.  Output
-*   values are coded on resp. 32-, 31- and 31- bits.
+*   See LFibRand78, LFibRand116, LFibRand668 and LFibRand1340 for large period  Lagged
+*   Fibonacci Generators  (resp.  2^78,  2^116,  2^668 and 2^1340 periods,  i.e. resp.
+*   3.0e+23, 8.3e+34, 1.2e+201 and 2.4e+403 periods) while same computation  time  and
+*   far higher precision (64-bits  calculations) but memory consumption (resp. 17, 55,
+*   607 and 1279 32-bits integers).
 *
-*   See LFibRand78, LFibRand116, LFibRand668 and LFibRand1340  for  long  period  LFib
-*   generators  (resp.  2^78,  2^116,  2^668  and 2^1340 periods,  i.e. resp. 3.0e+23,
-*   8.3e+34, 1.2e+201 and 2.4e+403 periods) while same computation time and far higher
-*   precision  (64-bits  calculations) but memory consumption (resp. 17,  55,  607 and
-*   1279 integers).
-* 
-*   See Xoroshiro256, Xoroshiro512, Xoroshiro1024 for long  period  generators  (resp. 
-*   2^256,  2^512  and  2^1024 periods,  i.e. resp. 1.16e+77,  1.34e+154 and 1.80e+308 
-*   periods),  64-bits precision calculations and short memory consumption  (resp.  4, 
-*   8 and 16 integers coded on 64 bits).
+*   See Melg607 for a  large  period  Maximally  Equidistributed  F2-Linear  Generator
+*   (2^607, i.e. 5.31e+182) with medium computation time and the equivalent of 21  32-
+*   bits integers memory little consumption.
+*   See Melg19937 for alarger period MELG-Generator (2^19,937, i.e. 4.32e+6001),  same
+*   computation time and equivalent of 625 integers memory consumption.
+*   See Melg44497 for a very large period (2^44,497,  i.e. 8.55e+13,395) with  similar
+*   computation  time  but  use of even more memory space (equivalent of 1,393 32-bits
+*   integers). This is the longest period version proposed in paper [11].
+*
+*   See Mrg287 for a short period Multiple Recursive Generator (2^287,  i.e. 2.49e+86)
+*   with low computation time but 256 32-bits integers memory consumption.
+*   See Mrg1457 for a longer period MR-Generator  (2^1457,  i.e. 4.0e+438)  and longer
+*   computation  time  (2^31-1 modulus calculations) but less memory space consumption
+*   (32-bits 47 integers).
+*   See Mrg49507 for a far larger period MR-Generator (2^49507, i.e. 1.2e+14903)  with
+*   low computation  time  too  (31-bits  modulus)  but use of more memory space (1597
+*   32-bits integers).
+*
+*   See Pcg64_32, Pcg128_64 and Pcg1024_32 for Permuted Congruential  Generators  with
+*   medium to very large periods,  very low computation time,  and for very low memory
+*   consumption for the two first (resp. 4, 8 and  1,026  times  32-bits).  Associated
+*   periods are resp. 2^64, 2^128 and 2^32830, i.e. 1.84e+19, 3.40e+38 and 6.53e+9882.
+*   These PRNGs provide multi-streams and jump ahead  features.  Since  they  all  are
+*   exposing  only  a part of their internal state,  they are difficult to reverse and
+*   to predict.
+*
+*   See Squares32 for a counter-based middle-square random number generator with  2^64
+*   (i.e. about 1.84e+19) period, low computation time, 32-bits output values and very
+*   good randomness characteristics.
+*   See Squares64 for a 2^64 (i.e. about 1.84e+19) period PRNG  with  low  computation
+*   time,   medium   period,   64-bits   output   values   and  very  good  randomness
+*   characteristics. Caution: this 64-bits version should not pass the birthday  test,
+*   which  is  a randomness issue, while this is not mentionned in the original paper.
+*
+*   See Well512a, Well1024a, Well19937c and Well44479b for large to very large  period
+*   generators (resp. 2^512, 2^1024, 2^19937 and 2^44479 periods, i.e. resp. 1.34e+154,
+*   2.68e+308,  4.32e+6001 and 1.51e+13466 periods),  a little bit longer  computation
+*   times but very quick escaping from zeroland.  Memory consumption is resp. 32,  64,
+*   624 and 1391 32-bits integers.
+*
+*   See Xoroshiro256, Xoroshiro512, Xoroshiro1024 for long  period  generators  (resp.
+*   2^256,  2^512  and  2^1024 periods,  i.e. resp. 1.16e+77,  1.34e+154 and 1.80e+308
+*   periods),  64-bits precision calculations and short memory consumption  (resp.  4,
+*   8 and 16 integers each coded on 64 bits.
 *
 *   Furthermore this class and all its inheriting sub-classes are callable. Example:
 * @code
@@ -80,7 +122,7 @@ SOFTWARE.
 *     std::cout << diceRoll.randint(1, 6) << std::endl; // prints also a uniform roll within range {1, ..., 6}
 * @endcode
 *
-*   Conforming to the former Python version of this library (CppRandLib), next methods
+*   Conforming to the former Python version of this library (i.e. PyRandLib), next methods
 *   are available - built-in function in Python module 'random':
 *    |
 *    |  betavariate(alpha, beta)
@@ -668,7 +710,6 @@ class BaseRandom
     inline void setstate(const StateT& new_internal_state, const double gauss_next) noexcept;
 
 
-
     /** @brief Returns the current internal state value. */
     inline const state_type state() const noexcept;
 
@@ -1661,10 +1702,10 @@ inline void BaseRandom<StateT, OutputT, OUTPUT_BITS>::seed(const utils::UInt128&
 template<typename StateT, typename OutputT, const std::uint8_t OUTPUT_BITS>
 inline void BaseRandom<StateT, OutputT, OUTPUT_BITS>::seed(const double seed_)
 {
-    if (seed_ < 0.0 || 1.0 <= seed_)
+    if (0.0 <= seed_ && seed_ <= 1.0)
+        seed(std::uint64_t(seed_ * double(0xffff'ffff'ffff'ffffULL)));
+    else
         throw FloatValueRange01Exception();
-
-    seed(std::uint64_t(seed_ * double(0xffff'ffff'ffff'ffffULL)));
 }
 
 //---------------------------------------------------------------------------
@@ -1743,7 +1784,7 @@ const double BaseRandom<StateT, OutputT, OUTPUT_BITS>::expovariate(const double
         throw ExponentialZeroLambdaException();
 
     const double u{ uniform() };
-    if (u < 1.0)  // should always happen, let's check for it nevertheless
+    if (u < 1.0)  // should always happen, let's check it nevertheless
         return -std::log(1.0 - u) / lambda;
     else
         return 0.0;

c++11/baseclasses/basewell.h

@@ -51,21 +51,24 @@ SOFTWARE.
 *   zeroland.
 *
 *   Notice: the algorithm in the 4 different versions implemented here has been  coded
-*   here  as  a  direct  implementation  of  their  descriptions  in the initial paper
-*   "Improved Long-Period Generators Based on Linear Recurrences  Modulo 2",  François
-*   PANNETON  and  Pierre  L’ECUYER  (Université  de  Montréal)  and  Makoto MATSUMOTO
-*   (Hiroshima University),  in ACM Transactions on  Mathematical  Software,  Vol. 32,
-*   No. 1, March 2006, Pages 1–16.
+*   as  a  direct  implementation of their descriptions in the initial paper "Improved
+*   Long-Period Generators Based on Linear Recurrences  Modulo 2",  François  PANNETON
+*   and  Pierre  L'ECUYER  (Université  de  Montréal)  and Makoto MATSUMOTO (Hiroshima
+*   University),  in ACM Transactions on Mathematical Software,  Vol. 32, No. 1, March
+*   2006, Pages 1-16.
 *   (see https://www.iro.umontreal.ca/~lecuyer/myftp/papers/wellrng.pdf).
 *   So,  only minimalist optimization has been coded,  with  the  aim  at  easing  the
 *   verification of its proper implementation.
 *
 *   See Well512a for a large period WELL-Generator (2^512,  i.e. 1.34e+154)  with  low
 *   computation time and 16 integers memory little consumption.
+* 
 *   See Well1024a for a longer period WELL-Generator (2^1,024,  i.e. 1.80e+308),  same
 *   computation time and 32 integers memory consumption.
+* 
 *   See Well199937c for a far longer period  (2^19,937, i.e. 4.32e+6,001) with similar
 *   computation time but use of more memory space (624 integers).
+* 
 *   See Well44497b for a very large period (2^44,497,  i.e. 15.1e+13,466) with similar
 *   computation time but use of even more memory space (1,391 integers).
 *

c++11/internalstates/extendedstate.h

@@ -34,7 +34,7 @@ SOFTWARE.
 
 
 //===========================================================================
-/** @brief The internal state of many Pseudo Random Numbers Generators. */
+/** @brief The internal extended state of some Pseudo Random Numbers Generators. */
 template<typename StateType, typename ExtendedValueType, const size_t EXTENDED_SIZE>
 struct ExtendedState
 {
@@ -48,7 +48,7 @@ struct ExtendedState
 
     inline ExtendedState() noexcept;    //!< Empty constructor
 
-    inline void seed(const std::uint64_t seed_) noexcept;   //!< state and external state inbitialization
+    inline void seed(const std::uint64_t seed_) noexcept;   //!< state and external state initialization
 
 };
 

c++11/mrg1457.h

@@ -60,6 +60,7 @@ SOFTWARE.
 *
 *   See Mrg287 for  a  short  period  MR-Generator  (2^287,  i.e. 2.49e+86)  with  low
 *   computation time but 256 integers memory consumption (2^32 modulus calculations).
+* 
 *   See Mrg49507 for a  far  longer  period  (2^49,507,  i.e.  1.2e+14,903)  with  low
 *   computation  time  too  (31-bits  modulus)  but  use  of  more memory space (1,597
 *   integers).

c++11/mrg287.h

@@ -77,6 +77,7 @@ SOFTWARE.
 *   See Mrg1457 for a longer period MR-Generator  (2^1457,  i.e. 4.0e+438)  and longer
 *   computation  time  (2^31-1 modulus calculations) but less memory space consumption
 *   (i.e. 47 integers).
+* 
 *   See Mrg49507 for  a  far  longer  period  (2^49,507,  i.e. 1.2e+14,903)  with  low
 *   computation  time  too  (31-bits  modulus)  but  use  of  more memory space (1,597
 *   integers).

c++11/mrg49507.cpp

@@ -107,9 +107,15 @@ const Mrg49507::output_type Mrg49507::next() noexcept
     const std::uint32_t k7{ (index < 7) ? (index + SEED_SIZE) - 7 : index - 7 };
 
     // evaluates current value and modifies internal state
+    const std::int64_t s = std::int64_t(_internal_state.state.list[k7]) + std::int64_t(_internal_state.state.list[index]);
+    const std::int64_t v1 = Mrg49507::_MULT * s;
+    const std::int64_t v2 = v1 % _MODULO;
+    const std::uint64_t value_ = v2 & 0x7fff'ffff;
+
     const std::uint64_t value{ 
-        (0xffff'ffff'fdff'ff80ull *  //i.e. (-2^25 - 2^7), or -67'108'992
-            std::uint64_t(_internal_state.state.list[k7] + _internal_state.state.list[index])
+        //(0xffff'ffff'fdff'ff80ull *  //i.e. (-2^25 - 2^7), or -67'108'992
+        (Mrg49507::_MULT *  //i.e. (-2^25 - 2^7)
+            std::int64_t(_internal_state.state.list[k7] + _internal_state.state.list[index])
         ) % _MODULO
     };
     _internal_state.state.list[index] = std::uint32_t(value);