Random generator supporting multiple PRNGs
Project description
RandomGen
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.
WARNINGS
Changes in v1.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 BigGenerators).
Future Plans
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 and RandomState. 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.
Python 2.7 Support
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.
Compatibility Warning
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.
Features
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.
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)
Support for Lemire’s method of generating uniform integers on an arbitrary interval by setting use_masked=True.
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**
ThreeFry and Philox from Random123
Differences from numpy.random.RandomState
Note
These comparrisons are relative to NumPy 1.16. The project has been substantially merged into NumPy 1.17+.
New Features relative to NumPy 1.16
standard_normal, normal, randn and multivariate_normal all use the much faster (100%+) Ziggurat method.
standard_gamma and gamma both use the much faster Ziggurat method.
standard_exponential exponential both support an additional method keyword argument which can be inv or zig where inv corresponds to the current method using the inverse CDF and zig 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 argument dtype
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.
New Functions
random_entropy - Read from the system entropy provider, which is commonly used in cryptographic applications
random_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.
Status
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)
Version
The package version matches the latest version of NumPy where RandomState(MT19937()) passes all NumPy test.
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.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.
Development and Testing
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.
Installing
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
SSE2
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
Windows
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.
Using
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)
License
Dual: BSD 3-Clause and NCSA, plus sub licenses for components.
Performance
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%
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for randomgen-1.18.0-cp38-cp38-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ee2077f8fe7ff69608db9c0d0c703b5de330866a464cf18dde994fdf39c5aa40 |
|
MD5 | 20f388cc226542314913eea544966efb |
|
BLAKE2b-256 | 5286ac01fcf993529a694231702ecdb43e33af5a4919ee18d07c7c9e50880af7 |
Hashes for randomgen-1.18.0-cp38-cp38-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ce40f81c07cbfcaa469cb94ed719afeb965d3da289b565b6b4f8ac5b0bea2c1 |
|
MD5 | d83e96f9aa654788e3c7b91c717bf670 |
|
BLAKE2b-256 | d235b8f8f12aed2ee4264c18b1a8752f744548e8b9c1c1f71ff99dcfca684550 |
Hashes for randomgen-1.18.0-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 258e44bcbd7d83923d5300b5e0e839e31270cedfa84fb7af39226d9e1e6609fa |
|
MD5 | 6e4a06582eb2363f4b1323939cf6ae6c |
|
BLAKE2b-256 | b80766a903b1ccb6b227d77dc39985e4b3d1a727a7c24abd23eefccd14e809ed |
Hashes for randomgen-1.18.0-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd2c2f9c33fb83b1810719e7d949bed7f1053e4a359166b9a844332b9c5297c8 |
|
MD5 | 6fbcdfe45770db74824b16fed1a2c70c |
|
BLAKE2b-256 | f918da192d00f6924b0b6df4ec3d650d55712ee165b8e34ae8015be2141a15d0 |
Hashes for randomgen-1.18.0-cp37-cp37m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5fa8ebafd55fa41fe0da322522cc4afa513ce9adcf5a14eae472e447cc6bd53f |
|
MD5 | cc17f2bbeccd911973600877f6584d04 |
|
BLAKE2b-256 | 679b76e91d14b8dd3be5cd225527de6a5ab1c30740049b7a42bb6bc8ecf44bf2 |
Hashes for randomgen-1.18.0-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5819a9f4ebd705e24bde2031463e769db2d55c12f6b67e357e03a315924d78b |
|
MD5 | 0587ea9a7ff9c9127c604cf5bd6b8f92 |
|
BLAKE2b-256 | e4c7c42e775fe0df4c80692f00a0e922cd8affa97dc79b844cbeddb15e1148f6 |
Hashes for randomgen-1.18.0-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bfd34688caa58abf9bb13c948dc8ad1a93ebfd155e4f1e159eedcd0360edd982 |
|
MD5 | eae664ed141b520bc5386e996c102efd |
|
BLAKE2b-256 | ba9c54f062b1fecf926daa73f7d645bbfea63af38ac1ce3f028f7aec570e6282 |
Hashes for randomgen-1.18.0-cp36-cp36m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5d90c34f903cdd0645c71e500c40b7dd712f35cf57508c3fe1eab28ec4eb32b1 |
|
MD5 | 09bf9d9cf25ea23996dd744915294c3e |
|
BLAKE2b-256 | 564c3207f8a11c6b634f34a57148ca0cab8fd68bfa237c896497c8de84ec14b6 |
Hashes for randomgen-1.18.0-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a75673243ecc694b98b740af15cd9fb8a6165197dd226ea591e56e84040e2212 |
|
MD5 | 78e15a76a8c909248757f93a3a59a63f |
|
BLAKE2b-256 | 1f2d1551b10a2a81a687b593c1e7cd95535942e3ed052bfaab930c1df6dc0f76 |
Hashes for randomgen-1.18.0-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4231981867e2148b07e3930ba2121e3b7c829a8ad6e2dcd2108347840a56d37b |
|
MD5 | d0c939350e78c7e9783d578c1aef534d |
|
BLAKE2b-256 | 2c34ea3f1e4ae29ae1f8bab2c026df7a704f9f8397aa720609493b938e8593ce |
Hashes for randomgen-1.18.0-cp35-cp35m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d811a883aeaacb812583a39e65b4e6746d64b8c5a52721872884e91a44b97202 |
|
MD5 | 78950cb61447cd9e389de1af8439d7d1 |
|
BLAKE2b-256 | 2e54a4165319cc254d30871f78b3f3404dbb460603082f4084a921d7eb2177c8 |
Hashes for randomgen-1.18.0-cp35-cp35m-macosx_10_6_intel.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ef45cd16fcaadab09f2c1fe005094f708c943e9ff3d1029e88aee5ce0a00008d |
|
MD5 | cd364ccbd2852be3c691b8613b0cb377 |
|
BLAKE2b-256 | c726495f8fbaa5386d9c50f249492777078d864bcca163bf150a874d2b1bc658 |