Py3 11 --> Dev

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016-2022 Philippe Schmouker, schmouk (at) gmail.com.
+Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com.
 
 Permission is hereby granted,  free of charge,  to any person obtaining a copy
 of this software and associated documentation files (the "Software"),  to deal

PyRandLib/__init__.py

@@ -3,19 +3,42 @@
 It is provided under MIT License.
 Please see files README.md and LICENSE.
 
-Copyright (c) 2016-2022 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com
 """
 
+from .basecwg        import BaseCWG
 from .baselcg        import BaseLCG
 from .baselfib64     import BaseLFib64
+from .basemelg       import BaseMELG
 from .basemrg        import BaseMRG
 from .baserandom     import BaseRandom
+from .basesquares    import BaseSquares
+from .basewell       import BaseWELL
+from .basexoroshiro  import BaseXoroshiro
+from .cwg64          import Cwg64
+from .cwg128_64      import Cwg128_64
+from .cwg128         import Cwg128
 from .fastrand32     import FastRand32
 from .fastrand63     import FastRand63
 from .lfib78         import LFib78
 from .lfib116        import LFib116
 from .lfib668        import LFib668
 from .lfib1340       import LFib1340
-from .mrgrand287     import MRGRand287
-from .mrgrand1457    import MRGRand1457
-from .mrgrand49507   import MRGRand49507
+from .melg607        import Melg607
+from .melg19937      import Melg19937
+from .melg44497      import Melg44497
+from .mrg287         import Mrg287
+from .mrg1457        import Mrg1457
+from .mrg49507       import Mrg49507
+from .pcg64_32       import Pcg64_32
+from .pcg128_64      import Pcg128_64
+from .pcg1024_32     import Pcg1024_32
+from .squares32      import Squares32
+from .squares64      import Squares64
+from .well512a       import Well512a
+from .well1024a      import Well1024a
+from .well19937c     import Well19937c
+from .well44497b     import Well44497b
+from .xoroshiro256   import Xoroshiro256
+from .xoroshiro512   import Xoroshiro512
+from .xoroshiro1024  import Xoroshiro1024

PyRandLib/annotation_types.py

@@ -0,0 +1,35 @@
+"""
+Copyright (c) 2021-2025 Philippe Schmouker, schmouk (at) gmail.com
+
+Permission is hereby granted,  free of charge,  to any person obtaining a copy
+of this software and associated documentation files (the "Software"),  to deal
+in the Software without restriction, including  without  limitation the rights
+to use,  copy,  modify,  merge,  publish,  distribute, sublicense, and/or sell
+copies of the Software,  and  to  permit  persons  to  whom  the  Software  is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY  KIND,  EXPRESS  OR
+IMPLIED,  INCLUDING  BUT  NOT  LIMITED  TO  THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT  SHALL  THE
+AUTHORS  OR  COPYRIGHT  HOLDERS  BE  LIABLE  FOR  ANY CLAIM,  DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  TORT OR OTHERWISE, ARISING FROM,
+OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+#=============================================================================
+from typing import List, Tuple, Union
+
+Numerical        = Union[ int, float ]
+StatesList       = Union[ Tuple[int], List[int] ]
+StatesListAndExt = Tuple[ StatesList, int ]
+StateType        = Union[ StatesList, StatesListAndExt ]
+SeedStateType    = Union[ Numerical, StateType ]
+
+
+#=====   end of   PyRandLib.annotation_types   ===============================
+
+# type: ignore  (this comment line is just to avoid boring pylance related error checking)

PyRandLib/basecwg.py

@@ -0,0 +1,113 @@
+"""
+Copyright (c) 2025 Philippe Schmouker, schmouk (at) gmail.com
+
+Permission is hereby granted,  free of charge,  to any person obtaining a copy
+of this software and associated documentation files (the "Software"),  to deal
+in the Software without restriction, including  without  limitation the rights
+to use,  copy,  modify,  merge,  publish,  distribute, sublicense, and/or sell
+copies of the Software,  and  to  permit  persons  to  whom  the  Software  is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY  KIND,  EXPRESS  OR
+IMPLIED,  INCLUDING  BUT  NOT  LIMITED  TO  THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT  SHALL  THE
+AUTHORS  OR  COPYRIGHT  HOLDERS  BE  LIABLE  FOR  ANY CLAIM,  DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  TORT OR OTHERWISE, ARISING FROM,
+OUT  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+#=============================================================================
+from .baserandom       import BaseRandom
+from .annotation_types import SeedStateType, StatesListAndExt
+
+
+#=============================================================================
+class BaseCWG( BaseRandom ):
+    """Definition of the base class for all Collatz-Weyl pseudo-random Generators.
+
+    This module is part of library PyRandLib.
+
+    Copyright (c) 2025 Philippe Schmouker
+
+    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.
+
+    See Cwg64 for a minimum  2^70  (i.e. about 1.18e+21)  period  CW-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 CW-Generator 
+    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  CW-generator
+    with very low computation time, medium period,  64- bits output values and 
+    very good randomness characteristics.
+
+    Furthermore this class is callable:
+      rand = BaseCWG()    # Caution: this is just used as illustrative. This base class cannot be instantiated
+      print( rand() )     # prints a pseudo-random value within [0.0, 1.0)
+      print( rand(a) )    # prints a pseudo-random value within [0, a) or [0.0, a) depending on the type of a
+      print( rand(a, n) ) # prints a list of n pseudo-random values each within [0, a)
+
+    Reminder:
+    We give you here below a copy of the table of tests for the CWGs that have 
+    been implemented in PyRandLib, as presented in paper [8] - see file README.md.
+
+ | PyRandLib class | [8] generator name | Memory Usage  | Period   | time-32bits | time-64 bits | SmallCrush fails | Crush fails | BigCrush fails |
+ | --------------- | ------------------ | ------------- | -------- | ----------- | ------------ | ---------------- | ----------- | -------------- |
+ | Cwg64           | CWG64              |   8 x 4-bytes | >= 2^70  |    n.a.     |     n.a.     |          0       |       0     |       0        |
+ | Cwg128_64       | CWG128_64          |  10 x 4-bytes | >= 2^71  |    n.a.     |     n.a.     |          0       |       0     |       0        |_
+ | Cwg128          | CWG128             |  16 x 4-bytes | >= 2^135 |    n.a.     |     n.a.     |          0       |       0     |       0        |
+
+    * _small crush_ is a small set of simple tests that quickly tests some  of
+    the expected characteristics for a pretty good PRNG;
+    * _crush_ is a bigger set of tests that test more deeply  expected  random 
+    characteristics;
+    * _big crush_ is the ultimate set of difficult tests that  any  GOOD  PRNG 
+    should definitively pass.
+    """
+
+    #-------------------------------------------------------------------------
+    def __init__(self, _seedState: SeedStateType = None) -> None:
+        """Constructor. 
+
+        Should _seedState be None then the local time is used as a seed  (with 
+        its shuffled value).
+        Notice: method setstate() is not implemented in base class BaseRandom.
+        So,  it  must be implemented in classes inheriting BaseLCG and it must
+        initialize attribute self._state.
+        """
+        super().__init__( _seedState )  # this internally calls 'setstate()'  which
+                                        # MUST be implemented in inheriting classes
+
+
+    #-------------------------------------------------------------------------
+    def getstate(self) -> StatesListAndExt:
+        """Returns an object capturing the current internal state of the generator.
+
+        This object can be passed to setstate() to restore the state.
+        For  CWG,  this  state is defined by a list of control values 
+        (a, weyl and s - or a list of 4 coeffs) and an internal state 
+        value,  which  are used in methods 'next() and 'setstate() of 
+        every inheriting class.
+
+        All inheriting classes MUST IMPLEMENT this method.
+        """
+        return (self._a, self._weyl, self._s, self._state)
+
+
+#=====   end of module   basecwg.py   ========================================

PyRandLib/baselcg.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
 """
-Copyright (c) 2016-2022 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com
 
 Permission is hereby granted,  free of charge,  to any person obtaining a copy
 of this software and associated documentation files (the "Software"),  to deal
@@ -23,7 +21,8 @@
 """
 
 #=============================================================================
-from .baserandom import BaseRandom
+from .baserandom       import BaseRandom
+from .annotation_types import Numerical
 
 
 #=============================================================================
@@ -32,19 +31,19 @@ class BaseLCG( BaseRandom ):
 
     This module is part of library PyRandLib.
 
-    Copyright (c) 2016-2021 Philippe Schmouker
+    Copyright (c) 2016-2025 Philippe Schmouker
 
     LCG models evaluate pseudo-random numbers suites x(i) as a simple mathem-
     atical function of 
 
         x(i-1): x(i) = (a*x(i-1) + c) mod m 
 
-    Results  are  nevertheless  considered  to  be  poor  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 not recommended to use such pseudo-random 
-    numbers generators for serious simulation applications.
+    Results are nevertheless considered to be poor 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 not recommended to use such pseudo-random numbers generators 
+    for serious simulation applications.
 
     See FastRand32 for a 2^32 (i.e. 4.3e+9) period LC-Generator with very  low 
     computation  time  but shorter period and worse randomness characteristics
@@ -54,73 +53,52 @@ class BaseLCG( BaseRandom ):
     characteristics than for FastRand32.
 
     Furthermore this class is callable:
-      rand = BaseLCG()
-      print( rand() )    # prints a uniform pseudo-random value within [0.0, 1.0)
-      print( rand(a) )   # prints a uniform pseudo-random value within [0.0, a)
-      print( rand(a,b) ) # prints a uniform pseudo-random value within [a  , b)
+      rand = BaseLCG()    # Caution: this is just used as illustrative. This base class cannot be instantiated
+      print( rand() )     # prints a pseudo-random value within [0.0, 1.0)
+      print( rand(a) )    # prints a pseudo-random value within [0, a) or [0.0, a) depending on the type of a
+      print( rand(a, n) ) # prints a list of n pseudo-random values each within [0, a)
 
     Reminder:
     We give you here below a copy of the table of tests for the LCGs that have 
     been implemented in PyRandLib, as provided in paper "TestU01, ..."  -  see
     file README.md.
 
- | PyRabndLib class | TU01 generator name                | Memory Usage    | Period  | time-32bits | time-64 bits | SmallCrush fails | Crush fails | BigCrush fails |
- | ---------------- | ---------------------------------- | --------------- | ------- | ----------- | ------------ | ---------------- | ----------- | -------------- |
- | FastRand32       | LCG(2^32, 69069, 1)                |     1 x 4-bytes | 2^32    |    3.20     |     0.67     |         11       |     106     |   *too many*   |
- | FastRand63       | LCG(2^63, 9219741426499971445, 1)  |     2 x 4-bytes | 2^63    |    4.20     |     0.75     |          0       |       5     |       7        |
+ | PyRandLib class | TU01 generator name                | Memory Usage    | Period  | time-32bits | time-64 bits | SmallCrush fails | Crush fails | BigCrush fails |
+ | --------------- | ---------------------------------- | --------------- | ------- | ----------- | ------------ | ---------------- | ----------- | -------------- |
+ | FastRand32      | LCG(2^32, 69069, 1)                |     1 x 4-bytes | 2^32    |    3.20     |     0.67     |         11       |     106     |   *too many*   |
+ | FastRand63      | LCG(2^63, 9219741426499971445, 1)  |     2 x 4-bytes | 2^63    |    4.20     |     0.75     |          0       |       5     |       7        |
 
     * _small crush_ is a small set of simple tests that quickly tests some  of
-    the expected characteristics for a pretty good PRG;
+    the expected characteristics for a pretty good PRNG;
     * _crush_ is a bigger set of tests that test more deeply  expected  random 
     characteristics;
-    * _big crush_ is the ultimate set of difficult tests  that  any  GOOD  PRG 
+    * _big crush_ is the ultimate set of difficult tests that  any  GOOD  PRNG 
     should definitively pass.
     """
 
-    #------------------------------------------------------------------------=
-    def __init__(self, _seedState: int = None) -> None:
+    #-------------------------------------------------------------------------
+    def __init__(self, _seedState: Numerical = None) -> None:
         """Constructor. 
 
-        Should inSeed be None or not an integer then the local 
-        time is used (with its shuffled value) as a seed.
+        Should _seedState be None then the local time is used as a seed  (with 
+        its shuffled value).
+        Notice: method setstate() is not implemented in base class BaseRandom.
+        So,  it  must be implemented in classes inheriting BaseLCG and it must
+        initialize attribute self._state.
         """
-        super().__init__( _seedState ) # this call creates attribute self._value and sets it
+        super().__init__( _seedState )  # this internally calls 'setstate()'  which
+                                        # MUST be implemented in inheriting classes
 
 
-    #------------------------------------------------------------------------=
-    def random(self) -> float:
-        """This is the core of the pseudo-random generator.
-
-        Returned values are within [0.0, 1.0).
-        Inheriting classes HAVE TO IMPLEMENT this method  -  see FastRand32
-        for an example. It should use and initialize attribute self._value.
-        """
-        raise NotImplementedError()
-
-
-    #------------------------------------------------------------------------=
+    #-------------------------------------------------------------------------
     def getstate(self) -> int:
         """Returns an object capturing the current internal state of the generator.
 
         This object can be passed to setstate() to restore the state.
-        For LCG,  the state is defined with  a  single  integer,  'self._value',
-        which  has  to  be  used  in  methods 'random() and 'setstate() of every
+        For LCG,  the state is defined with a single  integer,  'self._state',
+        which  has  to  be  used  in  methods 'next() and 'setstate() of every
         inheriting class.
         """
-        return self._value
-
-
-    #------------------------------------------------------------------------=
-    def setstate(self, _state: int) -> None:
-        """Restores the internal state of the generator.
-
-        _state should have been obtained from a previous call to getstate(),
-        and  setstate() restores the internal state of the generator to what
-        it was at the time setstate() was called.
-        Inheriting classes HAVE TO IMPLEMENT this method  -  see  FastRand32
-        for an example. It should initialize attribute self._value.
-        """
-        raise NotImplementedError()
-
+        return self._state
 
 #=====   end of module   baselcg.py   ========================================