License

PyRandLib is distributed under the MIT license for its largest use.
If you decide to use this library, please add the copyright notice to your software as stated in the LICENSE file.

Copyright (c) 2016-2026 Philippe Schmouker, <ph.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
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.

Intro

This library implements some of the best-in-class pseudo random generators as evaluated by Pierre L'Ecuyer and Richard Simard in their famous paper "TestU01: A C library for empirical testing of random number generators" (ACM Trans. Math. Softw. Vol. 33 N.4, August 2007 - see reference [1]). The reader will take benefit from reading L'Ecuyer & Simard's paper. This library implements also newer pseudo random generators that have been published since then. Their exhaustive list is provided here below and is valid for versions 2.0 and above of the library (i.e. since 2025/03):

Collatz-Weyl Generator (Tomasz R. Działa, 2023)
(CWG, 64 bits, 128 bits or 128/64 bits, 3 different values of periodicities, see reference [8]);
Linear Congruential Generator (Georges Marsaglia, 1972, F.B. Brown and Y. Nagaya, 2002)
(LCG, or FastRand, 32 bits or 63 bits, 2 different values of periodicities, see references [12] and [13] and [1]);
Lagged Fibonacci Generator (Georges Marsaglia, 1985)
(LFib, 64 bits, 4 different periodicities, see reference [4]);
Maximally Equidistributed Long-period Linear Generator (Shin Harase, Takamitsu Kimoto, 2018)
(MELG, 64/32 bits, 3 different values of periodicities, see reference [11]);
Multiple Recursive Generator (Lih-Yuan Deng & Dennis K. J. Lin., 2000, and Lih-Yuan Deng, 2005)
(MRG, 31 bits or 32 bits, 3 different values of periodicities, see references [2] and [3]);
Permutated Congruential Generator (Melissa E. O'Neill, 2014)
(PCG, 64, 128 bits or 64/32 bits, 3 different values of periodicities, see reference [7]);
Squares (ernard Widynski, 2022)
(Squares, 32 or 64 bits, 1 value of periodicity but 32- or 64-bits output values, see reference [9]);
Well-Equilibrated Long-period Linear generators (François Panneton, Pierre L'Ecuyer, Makoto Matsumoto, 2006)
(WELL, 32 bits, 4 different values of periodicities, see reference [6]);
Scrambled Linear Pseudorandom Number Generators (David Blackman, Sebastiano Vigna, 2018)
(Xoroshiro, 64 bits, 4 different values of periodicities, see reference [10]).

Each of the Pseudo Random Numbers Generator (PRNG) implemented in PyRandLib is self documented. Names of classes directly refer to the type of PRNG they implement augmented with some number characterizing their periodicity. All of their randomness characteristics are explained in every related module.

Latest version of PyRandLib is version 2.2, released by October 2025.

It provides implementations dedicated to different versions of Python: 3.6 (the original version of the library), 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14.
Time performances of every PRNG and for each version of Python (starting at 3.9) have been evaluated and are provided in tables below - see section CPU Performances.
Furthermore, starting from release 2.1 PyRandLib is fully validated. PyTest and PyTest-cov are now used to unit-test the code with a full 100% code coverage.

Why not Mersenne twister?

The Mersenne twister PRNG proposed by Matsumoto and Nishimura - see [5] - is the most widely used PRNG. The Random class of module random in Python implements this PRNG. It is also implemented in C++ and Java standard libraries for instance.

It offers a very good period (2^19937, i.e. about 4.3e6001). Unfortunately, this PRNG is a little bit long to compute (up to 3 times than LCGs, 60% more than LFibs and a little bit less than MRGs, see below at section 'Architecture overview'). Moreover, it fails four of the hardest TestU01 tests. You can still use it as your preferred PRNG but PyRandLib implements many other PRNGs that are either far faster or far better in terms of generated pseudo-randomness than the Mersenne twister PRNG.

Installation

Currently, the only way to install PyRandLib is to download the .zip or .tar.gz archive, then to directly put sub-directory PyRandLib\ from archive into directory Lib\site-packages\ of your Python environment. See https://schmouk.github.io/PyRandLib/ for an easy access to downloadable versions or click on tab releases on the home page of this GitHub repository.

Since release 2.0 of PyrandLib (Mar. 2025), the root directory of the library has been splitted into directories dedicated each to a different version of Python (3.6, 3.9, 3.10, etc.) Directory PyRandLib\ is now a sub-directory of each of these directories, with code optimized for the related Python version. Just copy into your dev environment the PyRandLib\ directory from the version of Python of your choice.

Since release 2.1 of PyRandLib (Jun. 2025), the whole code has been validated with unit tests (via pytest and pytest-cov). A few bugs have been fixed (protected method Pcg1024_32._externalstep() implementation, or a typo in a shifting constant in Well19937c.next() for instance). The code coverage rate is 100%. Pytest coverage output results are provided in files coverage-res.txt.
Release 2.0 of PyRandLib is nevertheless still available but it should no more be used.

Release 2.2 (Oct. 2025) provides code for Python 3.14. This code is identical to the one provided for Python 3.13, with a very few optimizations on some generators implementation. Notice: the CPU performance tests show that Python 3.14 runs faster than Python 3.13 on same PyRandLib code.

Notice: distribution version to be installed via pip or easy-install in cmd tool or in console is still to come (no date yet, expected with release 3.0 of PyRandLib).

Testing PyRandLib

The unit tests code is available for every Python standard version (3.6, 3.9 and above), in dedicated subdirectory unit-tests of every Python version directories.

Install pytest and pytest-cov

To run the unit tests by your own, you have to install first pytest and pytest-cov in your Python environment (or virtual environment, recommended). The procedure is desribed below.

Either in a Virtual environment

In a console, create a new virtual environment in a path of your choice on disk:

> python -m venv <path to the newly created virtual environment>

Activate it:

> <path to the newly created virtual environment>/Scripts/Activate.ps1 (for Windows Powershell)
or
> <path to the newly created virtual environment>/Scripts/activate.bat (for Windows console)
or
$ source <path to the newly created virtual environment>/bin/activate (on Linux)

Install pytest:

> python -m pip install --upgrade pip (not mandatory but always good to check)
> python -m pip install pytest

Install pytest-cov:

> python -m pip install pytest-cov

Or in your Python environment:

Install pytest:

> python -m pip install --upgrade pip
> python -m pip install pytest

Install pytest-cov:

> python -m pip install pytest-cov

Run the tests

Tests have been written to run in the context of a single Python standard version. Make the directory of your choice the working directory. For instance to test the Python3.13 version of PyRandLib just type:

> cd <path to your PyRandLib directory>/Python3.13

Then either run

> pytest --cov-config=.coveragerc --cov=. unit_tests

to get a full display of the code coverage and the detected failed tests (there should be none).

or run

> pytest --cov-config=.coveragerc --cov=. unit_tests --cov-report=html

to get an HTML version of the report, to be displayed by double-clicking on file <path to your PyRandLib directory>/Python3.13/htmlcov/index.html. This file will automatically open itself in your favorite web browser. Click on any not fully covered file to get a whole view of their code with highlighted missed statements (there should be none in official releases, just on current dev).

Expected results

In each of the subdirectories Python3.xx a text file tests-cov.txt contains a screen copy of the expected results.

PyRandLib

Install / Use

README