#219-fix typos in docstrings

Intermediate commit. Completeed and fully validated on all base classes.

Author: schmouk

Python3.10/PyRandLib/basecwg.py

@@ -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.
@@ -88,22 +90,22 @@ def __init__(self, _seedState: SeedStateType = None, /) -> None:  # type: ignore
         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
                                         # 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.
+        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.
         """

Python3.10/PyRandLib/baselcg.py

@@ -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.

Python3.10/PyRandLib/baselfib64.py

@@ -133,11 +133,20 @@ def __init__(self, _stateSize: int, _seedState: SeedStateType = None, /) -> None
 
     #-------------------------------------------------------------------------
     def seed(self, _seed: Numerical = None, /) -> None:  # type: ignore
+        """Initiates the internal state of this pseudo-random generator.
+        """
         super().seed( _seed )
 
 
     #-------------------------------------------------------------------------
     def setstate(self, _state: StateType = None, /) -> None:  # type: ignore
+        """Restores the internal state of the generator.
+        
+        _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.
+        """
         super().setstate(_state)
 
 

Python3.10/PyRandLib/basemrg.py

@@ -49,9 +49,11 @@ class BaseMRG( ListIndexState ):
        
     See Mrg287 for  a  shor t period  MR-Generator  (2^287,  i.e. 2.49e+86)  with  low
     computation time but 256 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 
     (47 integers).
+    
     See Mrg49507 for  a  far  longer  period  (2^49507,  i.e. 1.2e+14903)  with  lower 
     computation  time  too  (32-bits  modulus)  but  use  of  more  memory space (1597 
     integers).

Python3.10/PyRandLib/basepcg.py

@@ -38,10 +38,10 @@ class BasePCG( BaseRandom ):
  
        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 and have shown to pass all tests
     (Pierre  L'Ecuyer and Richard Simard (Universite de Montreal) in 'TestU01: 
@@ -110,7 +110,7 @@ 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._value',
+        For PCG,  the state is defined with  a  single  integer,  'self._value',
         which  has  to  be  used  in  methods 'random() and 'setstate() of every
         inheriting class.
         """

Python3.10/PyRandLib/baserandom.py

@@ -69,7 +69,7 @@ class BaseRandom( Random ):
     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 us  of more memory space (1597 
+    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 
@@ -97,8 +97,7 @@ class BaseRandom( Random ):
     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.
-
+    8 and 16 integers each coded on 64 bits.
 
     Python built-in class random.Random is subclassed here to use  a  different  basic 
     generator of our own devising: in that case, overriden methods are:
@@ -137,8 +136,6 @@ class BaseRandom( Random ):
      |      Binomial distribution. Return the number of successes for n 
      |      independent trials with the probability of success in each 
      |      trial being p.
-     |      Notice: added since Python 3.12, implemented in PyRandLib
-     |              for all previous versions of Python.
      |      n >= 0, 0.0 <= p <= 1.0,
      |      the result is an integer in the range 0 <= X <= n.
      |  
@@ -233,16 +230,11 @@ class BaseRandom( Random ):
      |      large population:   sample(range(10000000), 60)
      |  
      |
-     |  seed(self, a=None, version=2)
+     |  seed(self, a=None)
      |      Initialize internal state from hashable object.
      |      
      |      None or no argument seeds from current time or from an operating
      |      system specific randomness source if available.
-     |      
-     |      For version 2 (the default), all of the bits are used if *a *is a str,
-     |      bytes, or bytearray.  For version 1, the hash() of *a* is used instead.
-     |      
-     |      If *a* is an int, all bits are used.
      |  
      |
      |  setstate(self, state)

Python3.10/PyRandLib/basewell.py

@@ -50,24 +50,24 @@ class BaseWELL( ListIndexState ):
     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^1024,  i.e. 2.68e+308),  same 
     computation time and 32 integers memory consumption.
-    See Well199937b for a far longer period  (2^19937,  i.e. 4.32e+6001) with  similar 
+
+    See Well199937c for a far longer period  (2^19937,  i.e. 4.32e+6001) with  similar 
     computation time but use of more memory space (624 integers).
-    See Well44497b for a very large period (2^44497,  i.e. 15.1e+13466)  with  similar 
-    computation time but use of even more memory space (1,391 integers).
-    
+
     Please notice that this class and all its  inheriting  sub-classes  are  callable.
     Example:
     
@@ -129,11 +129,20 @@ def __init__(self, _stateSize: int, _seedState: SeedStateType = None, /) -> None
 
     #-------------------------------------------------------------------------
     def seed(self, _seed: Numerical = None, /) -> None:  # type: ignore
+        """Initiates the internal state of this pseudo-random generator.
+        """
         super().seed( _seed )
 
 
     #-------------------------------------------------------------------------
     def setstate(self, _state: StateType = None, /) -> None:  # type: ignore
+        """Restores the internal state of the generator.
+        
+        _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.
+        """
         super().setstate(_state)
 
 

Python3.10/PyRandLib/basexoroshiro.py

@@ -132,11 +132,20 @@ def __init__(self, _stateSize: int, _seedState: Numerical | StatesList = None, /
 
     #-------------------------------------------------------------------------
     def seed(self, _seed: Numerical = None, /) -> None:  # type: ignore
+        """Initiates the internal state of this pseudo-random generator.
+        """
         super().seed( _seed )
 
 
     #-------------------------------------------------------------------------
     def setstate(self, _state: StatesList = None, /) -> None:  # type: ignore
+        """Restores the internal state of the generator.
+        
+        _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.
+        """
         super().setstate(_state)
 
 

Python3.11/PyRandLib/basecwg.py

@@ -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.
@@ -88,22 +90,22 @@ def __init__(self, _seedState: SeedStateType = None, /) -> None:  # type: ignore
         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
                                         # 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.
+        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.
         """

Python3.11/PyRandLib/baselcg.py

@@ -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.