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

Release 2 1 2 --> Main

Author: schmouk

README.md

@@ -25,6 +25,28 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup CWG-algorithms algos: CWG - Collatz-Weyl Generators
+ *
+ *  This is the group for all the CppRandLib implementations of the Collatz-Weyl
+ *  pseudorandom Generators (CWG) algorithm.
+ *
+ *  CWG models are chaotic generators that are combined with Weyl sequences to
+ *  eliminate  the risk of short cycles.  They have a large period,  a uniform
+ *  distribution,  and the ability to generate multiple independent streams by
+ *  changing  their  internal  parameters  (Weyl  increment).  CWGs  owe their
+ *  exceptional  quality  to  the  arithmetical  dynamics   of  noninvertible,
+ *  generalized, Collatz mappings based on the wellknown Collatz conjecture.
+ *  There is no jump function, but each  odd  number  of  the  Weyl  increment
+ *  initiates  a  new  unique  period,  which  enables quick initialization of
+ *  independent streams (this text is extracted from [8], see README.md).
+ *
+ *  The internal implementation of the CWG algorithm varies according  to  its
+ *  implemented  version.  See  implementation  classes  to  get  their formal
+ *  description.
+ * 
+ *  @{
+ */
 
 //===========================================================================
 #include <cstdint>
@@ -321,3 +343,5 @@ inline void BaseCWG<ValueType, StateValueType, OutputType, OUTPUT_BITS>::_setsta
 {
     MyBaseClass::_internal_state.state.seed(seed_);
 }
+
+/** @}*/

c++11/baseclasses/basecwg.h

@@ -25,6 +25,34 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup LFib-algorithms algos: LFib - Lagged Fibonacci generators
+ *
+ *  This is the group for all the CppRandLib  implementations  of  the  Lagged
+ *  Fibonacci pseudorandom generators (LFib) algorithm.
+ *
+ *  Lagged Fibonacci generators LFib( m, r, k, op) use the recurrence
+ * @code
+ *       x(i) = (x(i-r) op (x(i-k)) mod m
+ * @endcode
+ *   where op is an operation that can be:
+ * @code
+ *       + (addition),
+ *       - (substraction),
+ *       * (multiplication),
+ *       ^ (bitwise exclusive-or).
+ * @endcode
+ * 
+ *   With the + or - operation, such generators are in fact MRGs.  They offer very large
+ *   periods  with  the  best  known  results  in the evaluation of their randomness, as
+ *   stated in the evaluation done by Pierre L'Ecuyer and Richard Simard  (Universite de
+ *   Montreal)  in  "TestU01:  A  C  Library  for  Empirical Testing  of  Random  Number
+ *   Generators  - ACM Transactions  on  Mathematical  Software,  vol.33 n.4,  pp.22-40,
+ *   August  2007".
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -363,3 +391,5 @@ inline void BaseLFib64<SIZE, K>::_setstate(const utils::UInt128& seed) noexcept
 {
     MyBaseClass::_setstate(seed);
 }
+
+/** @}*/

c++11/baseclasses/baselfib64.h

@@ -25,6 +25,25 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup MELG-algorithms algos: MELG - Maximally Equidistributed Long-period Linear Generators
+ *
+ *  This is the group for all the CppRandLib implementations  of  Maximally 
+ *  Equidistributed Long-period Linear Generators (MELG) algorithm.
+ *
+ *  Maximally Equidistributed  Long-period  Linear  Generators  (MELG)  use 
+ *  linear  recurrence  based  on  state  transitions with double feedbacks 
+ *  and linear output transformations with several memory references.
+ *
+ *  MELGs offer large to very large periods with best known results in  the
+ *  evaluation of their randomness. They ensure a maximally equidistributed
+ *  generation  of  pseudo random numbers.  They pass all TestU01 tests and 
+ *  newer ones but are the slowest to compute ones in  the  base  of  PRNGs 
+ *  that have been implemented in CppRandLib.
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -321,3 +340,5 @@ inline void BaseMELG<SIZE>::_setstate(const utils::UInt128& seed) noexcept
 {
     MyBaseClass::_setstate(seed);
 }
+
+/** @}*/

c++11/baseclasses/basemelg.h

@@ -25,6 +25,29 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup MRG-algorithms algos: MRG - Multiple Recursive Generators
+ *
+ *  This is the group for all the CppRandLib implementations of the Multiple
+ *  Recursive pseudorandom Generators (MRG) algorithm.
+ *
+ *  Multiple Recursive Generators (MRGs) use recurrence to evaluate  pseudo-
+ *  random numbers suites. Recurrence is of the form:
+ * @code
+ *      x(i) = A * SUM[ x(i-k) ]  mod M
+ * @endcode
+ *  for 2 to more k different values.
+ *
+ *  MRGs offer very large  periods  with  the  best  known  results  in  the
+ *  evaluation  of  their  randomness,  as  stated in the evaluation done by
+ *  by Pierre L'Ecuyer  and  Richard  Simard  (Universite  de  Montreal)  in 
+ *  "TestU01:  A C Library for Empirical Testing of Random Number Generators
+ *  - ACM Transactions on Mathematical Software, vol.33 n.4, pp.22-40, August
+ *  2007".
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -35,7 +58,7 @@ SOFTWARE.
 
 
 //===========================================================================
-/** @brief The base support for 32-bits MRG Pseudo Random Number Generators.
+/** @brief The base support for 31-bits MRG Pseudo Random Number Generators.
 *
 *   Multiple Recursive Generators (MRGs)  use  recurrence  to  evaluate  pseudo-random
 *   numbers suites. Recurrence is of the form:
@@ -324,3 +347,5 @@ inline void BaseMRG31<SIZE>::_setstate(const utils::UInt128& seed_) noexcept
 {
     MyBaseClass::_internal_state.state.seed(seed_.lo);
 }
+
+/** @}*/

c++11/baseclasses/basemrg31.h

@@ -25,6 +25,12 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @addtogroup MRG-algorithms
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -324,3 +330,5 @@ inline void BaseMRG32<SIZE>::_setstate(const utils::UInt128& seed_) noexcept
 {
     MyBaseClass::_internal_state.state.seed(seed_.lo);
 }
+
+/** @}*/

c++11/baseclasses/basemrg32.h

@@ -25,6 +25,37 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup PCG-algorithms algos: PCG - Permuted Congruential Generators
+ *
+ *  This is the group for all the CppRandLib implementations of  the  Permuted 
+ *  Congruential Generator (PCG) counter-based pseudorandom algorithm.
+ *
+ *  As LCGs do, PCG models evaluate pseudo-random numbers suites  x(i)  as  a
+ *  simple mathematical function of x(i-1):
+ * @code
+ *      x(i) = (a*x(i-1) + c) mod m
+ * @endcode
+ * 
+ *  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
+ *  (Universite de Montreal) in 'TestU01: A C Library for Empirical Testing of
+ *  Random  Number  Generators  -  ACM  Transactions on Mathematical Software,
+ *  vol.33 n.4, pp.22-40, August 2007')
+ *
+ *  PCGs are very fast generators, with low memory usage except for a very few
+ *  of them and medium to very large periods.  They offer jump ahead and multi
+ *  streams features for most of them. They are difficult to very difficult to
+ *  invert and to predict.
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include "baserandom.h"
@@ -105,3 +136,5 @@ SOFTWARE.
 */
 template<typename StateT, typename OutputT>
 using BasePCG = BaseRandom<StateT, OutputT, 8 * sizeof(OutputT)>;
+
+/** @}*/

c++11/baseclasses/basepcg.h

@@ -25,6 +25,15 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup BaseRandom algos: BaseRandom - Base class for all PRNGs (Pseudo Random Numbers Generators)
+ *
+ * This is the definition of the base class for all pseudo-random numbers generators
+ * that are implemented in CppRandLib.
+ * 
+ *  @{
+ */
+
 
 //===========================================================================
 #include <algorithm>
@@ -124,6 +133,7 @@ SOFTWARE.
 *
 *   Conforming to the former Python version of this library (i.e. PyRandLib), next methods
 *   are available - built-in function in Python module 'random':
+* @code
 *    |
 *    |  betavariate(alpha, beta)
 *    |      Beta distribution.
@@ -334,6 +344,7 @@ SOFTWARE.
 *    |      https://en.wikipedia.org/wiki/Weibull_distribution
 *    |
 *    |      alpha is the scale parameter and beta is the shape parameter.
+* @endcode
 */
 template<
     typename StateT,
@@ -2094,3 +2105,5 @@ const double BaseRandom<StateT, OutputT, OUTPUT_BITS>::weibullvariate(const doub
 
     return alpha * std::pow(-std::log(1.0 - uniform()), 1.0 / beta);
 }
+
+/** @}*/

c++11/baseclasses/baserandom.h

@@ -25,6 +25,21 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup Squares-algorithms algos: Squares - Squares counter-based pseudorandom generators
+ *
+ *  This is the group for all the CppRandLib  implementations  of  the  
+ *  Squares counter-based pseudorandom Generators (Squares) algorithm.
+ *
+ *  Squares models are based on an incremented counter and a key.  The
+ *  algorithm squares a combination of the counter and the key values,
+ *  and exchanges the upper and lower bits  of  the  combination,  the
+ *  whole  repeated  a number of times (4 to 5 rounds).  Output values
+ *  are provided on 32-bits or on 64-bits according to the model.
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -317,3 +332,5 @@ inline void BaseSquares<OutputT>::_setstate(const utils::UInt128& seed_) noexcep
     MyBaseClass::_internal_state.state.seed(seed_.lo);
     MyBaseClass::_internal_state.state.counter = 0;
 }
+
+/** @}*/

c++11/baseclasses/basesquares.h

@@ -25,6 +25,39 @@ OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @defgroup WELL-algorithms algos: WELL - Well-Equidistributed Long-period Linear generators
+ *
+ *  This  is  the  group  for  all  the  CppRandLib  implementations  of   the   Well-
+ *  Equidistributed  Long-period  Linear  Generators  pseudo-random  generators (WELL) 
+ *  algorithm.
+ *
+ *  Well-Equidistributed Long-period Linear Generators (WELL)  use  linear  recurrence
+ *  based  on  primitive  characteristic  polynomials associated with left- and right-
+ *  shifts and xor operations to fastly evaluate pseudo-random numbers suites.
+ *
+ *  WELLs offer large to very large periods with best known results in the  evaluation
+ *  of their randomness,  as stated in the evaluation  done  by  Pierre  L'Ecuyer  and
+ *  Richard Simard (Universite de Montreal) in  "TestU01:  A C Library  for  Empirical
+ *  Testing of Random  Number Generators  - ACM Transactions on Mathematical Software,
+ *  vol.33 n.4, pp.22-40, August 2007".  It is recommended to use  such  pseudo-random
+ *  numbers generators rather than LCG ones for serious simulation applications.
+ *  Furthermore, WELLs have proven their great ability  to  very  fastly  escape  from
+ *  zeroland.
+ *
+ *  Notice: the algorithm in the 4 different versions implemented here has been  coded
+ *  as  a  direct  implementation of their descriptions in the initial paper "Improved
+ *  Long-Period Generators Based on Linear Recurrences  Modulo 2",  Francois  PANNETON
+ *  and  Pierre  L'ECUYER  (Universite  de  Montreal)  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.
+ *
+ *  @{
+ */
+
 
 //===========================================================================
 #include <cstdint>
@@ -52,8 +85,8 @@ SOFTWARE.
 *
 *   Notice: the algorithm in the 4 different versions implemented here has been  coded
 *   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
+*   Long-Period Generators Based on Linear Recurrences  Modulo 2",  Francois  PANNETON
+*   and  Pierre  L'ECUYER  (Universite  de  Montreal)  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).
@@ -493,3 +526,5 @@ inline typename BaseWell<SIZE>::value_type BaseWell<SIZE>::_tempering(
     value_type x_{ x ^ (((x << 7) & 0xffff'fffful) & b) };
     return x_ ^ (((x_ << 15) & 0xffff'fffful) & c);
 }
+
+/** @}*/