Random Number Generator using settable Basic RNG interface for future NumPy RandomState evolution.
Continuous Integration
Coverage
Latest Release
License
This is a library and generic interface for alternative random generators in Python and NumPy.
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 DeprecationWarning
s 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 BigGenerator
s).
A substantial portion of randomgen has been merged into NumPy. Revamping NumPy's random number generation was always the goal of this project (and its predecessor NextGen NumPy RandomState), and so it has succeeded.
While I have no immediate plans to remove anything, after a 1.19 release I will:
- Remove
Generator
andRandomState
. These duplicate NumPy and will diverge over time. The versions in NumPy are authoritative. - Preserve novel methods of
Generator
in a new class,ExtendedGenerator
. - Add some distributions that are not supported in NumPy.
- Remove
MT19937
PCG64
since these are duplicates of bit generators in NumPy. - Add any interesting bit generators I come across.
v1.16 is the final major version that supports Python 2.7. Any bugs in v1.16 will be patched until the end of 2019. All future releases are Python 3, with an initial minimum version of 3.5.
Generator
does not support Box-Muller normal variates and so it not
100% compatible with NumPy (or randomstate). Box-Muller normals are slow
to generate and all functions which previously relied on Box-Muller
normals now use the faster Ziggurat implementation. If you require backward
compatibility, a legacy generator, RandomState
, has been created
which can fully reproduce the sequence produced by NumPy.
-
Designed as a peplacement for NumPy's 1.16's RandomState
from randomgen import Generator, MT19937 rnd = Generator(MT19937()) x = rnd.standard_normal(100) y = rnd.random(100) z = rnd.randn(10,10)
-
Default random generator is a fast generator called Xoroshiro128plus
-
Support for random number generators that support independent streams and jumping ahead so that sub-streams can be generated
-
Faster random number generation, especially for normal, standard exponential and standard gamma using the Ziggurat method
from randomgen import Generator # Default bit generator is Xoroshiro128 rnd = Generator() w = rnd.standard_normal(10000) x = rnd.standard_exponential(10000) y = rnd.standard_gamma(5.5, 10000)
-
Support for 32-bit floating randoms for core generators. Currently supported:
- Uniforms (
random
) - Exponentials (
standard_exponential
, both Inverse CDF and Ziggurat) - Normals (
standard_normal
) - Standard Gammas (via
standard_gamma
)
WARNING: The 32-bit generators are experimental and subject to change.
Note: There are no plans to extend the alternative precision generation to all distributions.
- Uniforms (
-
Support for filling existing arrays using
out
keyword argument. Currently supported in (both 32- and 64-bit outputs)- Uniforms (
random
) - Exponentials (
standard_exponential
) - Normals (
standard_normal
) - Standard Gammas (via
standard_gamma
)
- Uniforms (
-
Support for Lemire's method of generating uniform integers on an arbitrary interval by setting
use_masked=True
.
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
These comparrisons are relative to NumPy 1.16. The project has been substantially merged into NumPy 1.17+.
standard_normal
,normal
,randn
andmultivariate_normal
all use the much faster (100%+) Ziggurat method.standard_gamma
andgamma
both use the much faster Ziggurat method.standard_exponential
exponential
both support an additionalmethod
keyword argument which can beinv
orzig
whereinv
corresponds to the current method using the inverse CDF andzig
uses the much faster (100%+) Ziggurat method.- Core random number generators can produce either single precision
(
np.float32
) or double precision (np.float64
, the default) using the optional keyword argumentdtype
- Core random number generators can fill existing arrays using the
out
keyword argument - Standardizes integer-values random values as int64 for all platforms.
randint
supports generating using rejection sampling on masked values (the default) or Lemire's method. Lemire's method can be much faster when the required interval length is much smaller than the closes power of 2.
random_entropy
- Read from the system entropy provider, which is commonly used in cryptographic applicationsrandom_raw
- Direct access to the values produced by the underlying PRNG. The range of the values returned depends on the specifics of the PRNG implementation.random_uintegers
- unsigned integers, either 32- ([0, 2**32-1]
) or 64-bit ([0, 2**64-1]
)jump
- Jumps RNGs that support it.jump
moves the state a great distance. Only available if supported by the RNG.advance
- Advanced the RNG 'as-if' a number of draws were made, without actually drawing the numbers. Only available if supported by the RNG.
- Builds and passes all tests on:
- Linux 32/64 bit, Python 2.7, 3.5, 3.6, 3.7
- Linux (ARM/ARM64), Python 3.7
- OSX 64-bit, Python 2.7, 3.5, 3.6, 3.7
- Windows 32/64 bit, Python 2.7, 3.5, 3.6, 3.7
- PC-BSD (FreeBSD) 64-bit, Python 2.7 (Occasional, no CI)
The package version matches the latest version of NumPy where
RandomState(MT19937())
passes all NumPy test.
Documentation for the latest release is available on my GitHub pages. Documentation for the latest commit (unreleased) is available under devel.
Building requires:
- Python (3.5, 3.6, 3.7, 3.8)
- NumPy (1.13, 1.14, 1.15, 1.16, 1.17, 1.18)
- Cython (0.26+)
- tempita (0.5+), if not provided by Cython
Testing requires pytest (4.0+).
Note: it might work with other versions but only tested with these versions.
All development has been on 64-bit Linux, and it is regularly tested on Travis-CI (Linux/OSX), Appveyor (Windows), Cirrus (FreeBSD) and Drone.io (ARM/ARM64 Linux).
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.
Either install from PyPi using
pip install randomgen
or, if you want the latest version,
pip install git+https://github.com/bashtage/randomgen.git
or from a cloned repo,
python setup.py install
dSFTM
makes use of SSE2 by default. If you have a very old computer
or are building on non-x86, you can install using:
python setup.py install --no-sse2
Either use a binary installer, or if building from scratch, use Python 3.6/3.7 with Visual Studio 2015/2017 Community Edition. It can also be build using Microsoft Visual C++ Compiler for Python 2.7 and Python 2.7.
The separate generators are importable from randomgen
from randomgen import Generator, ThreeFry, PCG64, MT19937
rg = Generator(ThreeFry())
rg.random(100)
rg = Generator(PCG64())
rg.random(100)
# Identical to NumPy
rg = Generator(MT19937())
rg.random(100)
Dual: BSD 3-Clause and NCSA, plus sub licenses for components.
Performance is promising, and even the mt19937 seems to be faster than NumPy's mt19937.
Speed-up relative to NumPy (Uniform Doubles)
************************************************************
DSFMT 184.9%
MT19937 17.3%
PCG32 83.3%
PCG64 108.3%
Philox -4.9%
ThreeFry -12.0%
Xoroshiro128 159.5%
Xorshift1024 150.4%
Xoshiro256 145.7%
Xoshiro512 113.1%
Speed-up relative to NumPy (64-bit unsigned integers)
************************************************************
DSFMT 17.4%
MT19937 7.8%
PCG32 60.3%
PCG64 73.5%
Philox -25.5%
ThreeFry -30.5%
Xoroshiro128 124.0%
Xorshift1024 109.4%
Xoshiro256 100.3%
Xoshiro512 63.5%
Speed-up relative to NumPy (Standard normals)
************************************************************
DSFMT 183.0%
MT19937 169.0%
PCG32 240.7%
PCG64 231.6%
Philox 131.3%
ThreeFry 118.3%
Xoroshiro128 332.1%
Xorshift1024 232.4%
Xoshiro256 306.6%
Xoshiro512 274.6%