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

Release 2 1

Author: schmouk

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com.
+Copyright (c) 2016-2025 Philippe Schmouker, ph (dot) schmouker (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

Python3.10/.coveragerc

@@ -0,0 +1,7 @@
+[run]
+omit = unit_tests/* \
+    test*.py    
+
+[report]
+fail_under = 100
+precision = 0

Python3.10/PyRandLib/__init__.py

@@ -3,7 +3,7 @@
 It is provided under MIT License.
 Please see files README.md and LICENSE.
 
-Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2016-2025 Philippe Schmouker, ph (dot) schmouker (at) gmail.com
 """
 
 from .basecwg        import BaseCWG

Python3.10/PyRandLib/annotation_types.py

@@ -1,5 +1,5 @@
 """
-Copyright (c) 2021-2025 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2021-2025 Philippe Schmouker, ph (dot) schmouker (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
@@ -29,5 +29,3 @@
 
 
 #=====   end of   PyRandLib.annotation_types   ===============================
-
-# type: ignore  (this comment line is just to avoid boring pylance related error checking)

Python3.10/PyRandLib/basecwg.py

@@ -1,5 +1,5 @@
 """
-Copyright (c) 2025 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2025 Philippe Schmouker, ph (dot) schmouker (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
@@ -50,9 +50,11 @@ class BaseCWG( BaseRandom ):
     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.
@@ -70,7 +72,7 @@ class BaseCWG( BaseRandom ):
  | 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_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
@@ -82,13 +84,13 @@ class BaseCWG( BaseRandom ):
     """
 
     #-------------------------------------------------------------------------
-    def __init__(self, _seedState: SeedStateType = None, /) -> None:
+    def __init__(self, _seedState: SeedStateType = None, /) -> None:  # type: ignore
         """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
+        So,  it  must be implemented in classes inheriting BaseCWG and it must
         initialize attribute self._state.
         """
         super().__init__( _seedState )  # this internally calls 'setstate()'  which
@@ -99,15 +101,15 @@ def __init__(self, _seedState: SeedStateType = None, /) -> None:
     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.
+        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, s and an internal state value - or a list of 4 coeffs),
+        which  are  used  in methods 'next() and 'setstate() of every in-
+        heriting class.
 
         All inheriting classes MUST IMPLEMENT this method.
         """
-        return (self._a, self._weyl, self._s, self._state)
-   
+        return (self._a, self._weyl, self._s, self._state)  # type: ignore
+
 
 #=====   end of module   basecwg.py   ========================================

Python3.10/PyRandLib/baselcg.py

@@ -1,5 +1,5 @@
 """
-Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2016-2025 Philippe Schmouker, ph (dot) schmouker (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
@@ -48,6 +48,7 @@ class BaseLCG( BaseRandom ):
     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
     than for FastRand63.
+    
     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.
@@ -77,7 +78,7 @@ class BaseLCG( BaseRandom ):
     """
 
     #-------------------------------------------------------------------------
-    def __init__(self, _seedState: Numerical = None, /) -> None:
+    def __init__(self, _seedState: Numerical = None, /) -> None:  # type: ignore
         """Constructor. 
         
         Should _seedState be None then the local time is used as a seed  (with 
@@ -91,15 +92,15 @@ def __init__(self, _seedState: Numerical = None, /) -> None:
 
 
     #-------------------------------------------------------------------------
-    def getstate(self) -> int:
+    def getstate(self) -> int:  # type: ignore
         """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._state',
         which  has  to  be  used  in  methods 'next() and 'setstate() of every
         inheriting class.
         """
-        return self._state
+        return self._state  # type: ignore
 
 
 #=====   end of module   baselcg.py   ========================================

Python3.10/PyRandLib/baselfib64.py

@@ -1,5 +1,5 @@
 """
-Copyright (c) 2016-2025 Philippe Schmouker, schmouk (at) gmail.com
+Copyright (c) 2016-2025 Philippe Schmouker, ph (dot) schmouker (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,13 +23,13 @@
 #=============================================================================
 from typing import Final
 
-from .baserandom       import BaseRandom
+from .listindexstate   import ListIndexState
 from .annotation_types import Numerical, SeedStateType, StateType
 from .splitmix         import SplitMix64
 
 
 #=============================================================================
-class BaseLFib64( BaseRandom ):
+class BaseLFib64( ListIndexState ):
     """The base class for all LFib PRNG based on 64-bits numbers.
     
     Definition of the base class for all LFib pseudo-random generators based
@@ -47,7 +47,7 @@ class BaseLFib64( BaseRandom ):
         + (addition),
         - (substraction),
         * (multiplication),
-        ^(bitwise exclusive-or).
+        ^ (bitwise exclusive-or).
     
     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
@@ -81,10 +81,10 @@ class BaseLFib64( BaseRandom ):
 
  | PyRandLib class | TU01 generator name      | Memory Usage    | Period  | time-32bits | time-64 bits | SmallCrush fails | Crush fails | BigCrush fails |
  | --------------- | ------------------------ | --------------- | ------- | ----------- | ------------ | ---------------- | ----------- | -------------- |
- | LFibRand78      | LFib(2^64, 17, 5, +)     |    34 x 4-bytes | 2^78    |    n.a.     |     1.1      |          0       |       0     |       0        |
- | LFibRand116     | LFib(2^64, 55, 24, +)    |   110 x 4-bytes | 2^116   |    n.a.     |     1.0      |          0       |       0     |       0        |
- | LFibRand668     | LFib(2^64, 607, 273, +)  | 1,214 x 4-bytes | 2^668   |    n.a.     |     0.9      |          0       |       0     |       0        |
- | LFibRand1340    | LFib(2^64, 1279, 861, +) | 2,558 x 4-bytes | 2^1340  |    n.a.     |     0.9      |          0       |       0     |       0        |
+ | LFib78          | LFib(2^64, 17, 5, +)     |    34 x 4-bytes | 2^78    |    n.a.     |     1.1      |          0       |       0     |       0        |
+ | LFib116         | LFib(2^64, 55, 24, +)    |   110 x 4-bytes | 2^116   |    n.a.     |     1.0      |          0       |       0     |       0        |
+ | LFib668         | LFib(2^64, 607, 273, +)  | 1,214 x 4-bytes | 2^668   |    n.a.     |     0.9      |          0       |       0     |       0        |
+ | LFib1340        | LFib(2^64, 1279, 861, +) | 2,558 x 4-bytes | 2^1340  |    n.a.     |     0.9      |          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;
@@ -96,111 +96,58 @@ class BaseLFib64( BaseRandom ):
 
 
     #-------------------------------------------------------------------------
-    _NORMALIZE: Final[float] = 5.421_010_862_427_522_170_037_3e-20  # i.e. 1.0 / (1 << 64)
+    _NORMALIZE: Final[float] = 5.421_010_862_427_522_170_037_3e-20  # i.e. 1.0 / (1 << 64)  # type: ignore
     """The value of this class attribute MUST BE OVERRIDDEN in  inheriting
     classes  if  returned random integer values are coded on anything else 
     than 32 bits.  It is THE multiplier constant value to  be  applied  to  
     pseudo-random number for them to be normalized in interval [0.0, 1.0).
     """
 
-    _OUT_BITS: Final[int] = 64
+    _OUT_BITS: Final[int] = 64  # type: ignore
     """The value of this class attribute MUST BE OVERRIDDEN in inheriting
     classes  if returned random integer values are coded on anything else 
     than 32 bits.
     """
 
 
     #-------------------------------------------------------------------------
-    def __init__(self, _seedState: SeedStateType = None, /) -> None:
+    def __init__(self, _stateSize: int, _seedState: SeedStateType = None, /) -> None:  # type: ignore
         """Constructor.
         
+        _stateSize is the size of the internal state list of integers.
         _seedState is either a valid state, an integer,  a float or None.
         About  valid  state:  this  is  a  tuple  containing  a  list  of  
-        self._STATE_SIZE integers and  an index in this list (index  value 
-        being  then  in range (0,self._STATE_SIZE)).  Should _seedState be 
-        a sole integer or float then it  is  used  as  initial  seed  for 
-        the  random  filling  of  the  internal  list  of self._STATE_SIZE  
+        self._STATE_SIZE  64-bits  integers  and  an  index  in this list 
+        (index value being  then  in range (0,self._STATE_SIZE)).  Should 
+        _seedState be a sole integer or float then it is used as  initial
+        seed for the random filling of the internal list of self._STATE_SIZE  
         integers.  Should _seedState be anything else  (e.g.  None)  then  
         the  shuffling of the local current time value is used as such an 
         initial seed.
         """
-        super().__init__( _seedState )
+        super().__init__( SplitMix64, _stateSize, _seedState )
             # this  call  creates  the  two   attributes
             # self._state and self._index, and sets them
             # since it internally calls self.setstate().
 
 
     #-------------------------------------------------------------------------
-    def getstate(self) -> StateType:
-        """Returns an object capturing the current internal state of the  generator.
-        
-        This  object can be passed to setstate() to restore the state.  It is a
-        tuple containing a list of self._STATE_SIZE integers and an 
-        index in this list (index value being then in range(0,self._STATE_SIZE).
+    def seed(self, _seed: Numerical = None, /) -> None:  # type: ignore
+        """Initiates the internal state of this pseudo-random generator.
         """
-        return (self._state[:], self._index)
+        super().seed( _seed )
 
 
     #-------------------------------------------------------------------------
-    def setstate(self, _seedState: StateType, /) -> None:
+    def setstate(self, _state: StateType = None, /) -> None:  # type: ignore
         """Restores the internal state of the generator.
         
-        _seedState 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.
-        About valid state:  this is a  tuple  containing  a  list  of 
-        self._STATE_SIZE integers (31-bits) and an index in this list 
-        (index value being then in range(0,self._STATE_SIZE)). Should 
-        _seedState  be  a  sole  integer  or float then it is used as 
-        initial seed for the random filling of the internal  list  of 
-        self._STATE_SIZE integers. Should _seedState be anything else
-        (e.g. None) then the shuffling  of  the  local  current  time
-        value is used as such an initial seed.
-        """
-        try:
-            match len( _seedState ):
-                case 0:
-                    self._index = 0
-                    self._initstate()
-                
-                case 1:
-                    self._index = 0
-                    self._initstate( _seedState[0] )
-                
-                case _:
-                    self._initindex( _seedState[1] )
-                    if (len(_seedState[0]) == self._STATE_SIZE):
-                        self._state = _seedState[0][:]    # each entry in _seedState MUST be integer
-                    else:
-                        self._initstate( _seedState[0] )
-                
-        except:
-            self._index = 0
-            self._initstate( _seedState )
-
-
-    #-------------------------------------------------------------------------
-    def _initindex(self, _index: int, /) -> None:
-        """Inits the internal index pointing to the internal list.
+        _state should have been obtained from a previous call to getstate().
+        'setstate()' restores the internal state of the generator to what it
+        was at the time getstate() was lastly called.
+        Inheriting classes MUST IMPLEMENT this method.
         """
-        try:
-            self._index = int( _index ) % self._STATE_SIZE
-        except:
-            self._index = 0
-
-
-    #-------------------------------------------------------------------------
-    def _initstate(self, _initialSeed: Numerical = None, /) -> None:
-        """Inits the internal list of values.
-        
-        Inits the internal list of values according to some initial
-        seed  that  has  to be an integer or a float ranging within
-        [0.0, 1.0).  Should it be None or anything  else  then  the
-        current local time value is used as initial seed value.
-        """
-        initRand = SplitMix64( _initialSeed )
-        self._state = [ initRand() for _ in range(self._STATE_SIZE) ]        
+        super().setstate(_state)
 
 
 #=====   end of module   baselfib64.py   =====================================
-