RandomGen

This package contains additional bit generators for NumPy's Generator and an ExtendedGenerator exposing methods not in Generator.

Continuous Integration

Coverage

Latest Release

License

This is a library and generic interface for alternative random generators in Python and NumPy.

New Features

See the development documentation for the latest features, or the stable documentation for the latest released features.

WARNINGS

Changes in v1.24

Generator and RandomState were removed in 1.23.0.

Changes from 1.18 to 1.19

Generator and RandomState have been officially deprecated in 1.19, and will warn with a FutureWarning about their removal. They will also receive virtually no maintenance. It is now time to move to NumPy's np.random.Generator which has features not in randomstate.Generator and is maintained more actively.

A few distributions that are not present in np.random.Generator have been moved to randomstate.ExtendedGenerator:

• multivariate_normal: which supports broadcasting
• uintegers: fast 32 and 64-bit uniform integers
• complex_normal: scalar complex normals

There are no plans to remove any of the bit generators, e.g., AESCounter, ThreeFry, or PCG64.

Changes from 1.16 to 1.18

There are many changes between v1.16.x and v1.18.x. These reflect API decision taken in conjunction with NumPy in preparation of the core of randomgen being used as the preferred random number generator in NumPy. These all issue DeprecationWarnings except for BasicRNG.generator which raises NotImplementedError. The C-API has also changed to reflect the preferred naming the underlying Pseudo-RNGs, which are now known as bit generators (or BitGenerators).

Future Plans

• Add some distributions that are not supported in NumPy. Ongoing
• Add any interesting bit generators I come across. Recent additions include the DXSM and CM-DXSM variants of PCG64 and the LXM generator.

Included Pseudo Random Number Generators

This module includes a number of alternative random number generators in addition to the MT19937 that is included in NumPy. The RNGs include:

• Cryptographic cipher-based random number generator based on AES, ChaCha20, HC128 and Speck128.
• MT19937, the NumPy rng
• dSFMT a SSE2-aware version of the MT19937 generator that is especially fast at generating doubles
• xoroshiro128+, xorshift1024*φ, xoshiro256**, and xoshiro512**
• PCG64
• ThreeFry and Philox from Random123
• Other cryptographic-based generators: AESCounter, SPECK128, ChaCha, and HC128.
• Hardware (non-reproducible) random number generator on AMD64 using RDRAND.
• Chaotic PRNGS: Small-Fast Chaotic (SFC64) and Jenkin's Small-Fast (JSF).

Status

• Builds and passes all tests on:
  • Linux 64-bit (x86-64), Python 3.10, 3.11, 3.12, 3.13, 3.14, 3.15
  • Linux ARM64, current Python
  • macOS, Python 3.10, 3.11, 3.12, 3.15
  • Windows 64-bit, Python 3.10, 3.11, 3.12, 3.13, 3.14, 3.15
  • Free-threaded Python 3.14t and 3.15t on Linux, macOS and Windows

Version

The package version matches the latest version of NumPy when the package is released.

Documentation

Documentation for the latest release is available on my GitHub pages. Documentation for the latest commit (unreleased) is available under devel.

Requirements

Building requires:

• Python (3.10, 3.11, 3.12, 3.13, 3.14, 3.15)
• NumPy (1.26+ except 2.4.0, runtime; 2.0.0+, building)
• Cython (3.1.0+)

Testing requires pytest (9+).

The development dependencies are dependency groups in pyproject.toml. With pip 25.1 or later, install everything needed to build, test and lint randomgen, and then randomgen itself, with

python -m pip install --group dev
python -m pip install -e . --no-build-isolation

The groups are build, test, lint, doc (for the documentation) and dev (build, test and lint together).

Note: it might work with other versions but only tested with these versions.

Development and Testing

All development has been on 64-bit Linux, and it is regularly tested on Azure (Linux-AMD64, Windows, and macOS) and GitHub Actions (Linux-ARM64 and free-threaded Python).

Tests are in place for all RNGs. The MT19937 is tested against NumPy's implementation for identical results. It also passes NumPy's test suite where still relevant.

Installing

Either install from PyPi using

python -m pip install randomgen

or, if you want the latest version,

python -m pip install git+https://github.com/bashtage/randomgen.git

or from a cloned repo,

python -m pip install .

If you use conda, you can install using conda forge

conda install -c conda-forge randomgen

SSE2

dSFMT and SFMT make use of SSE2 by default. If you have a very old computer or are building on non-x86, you can install using:

python -m pip install . -Csetup-args=-Ddisable-sse2=true

Windows

Either use a binary wheel, or if building from scratch, use the Visual Studio Build Tools (MSVC). Builds with clang-cl are also tested.

License

Dual: BSD 3-Clause and NCSA, plus sub licenses for components.