This package contains replacements for the NumPy RandomState object that allows the core random number generator be be changed.


There are many changes between v1.16.x and v1.17.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 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 BitGenerator).

The main changes are

  • Rename RandomGenerator to Generator.

  • Rename randint() to integers().

  • Rename random_integers() to integers().

  • Rename random_sample() to random().

  • Change jump which operated in-place to jumped which returns a new BitGenerator.

  • Rename Basic RNG to bit generator, which impacts the API in multiple places where names like brng and basic_rng have been replaced by bitgen or bit_generator.

v1.16.x will be updated until the end of 2019 if you want to avoid these changes.

Quick Start

Like numpy.random, RandomGen can be used at the module level. This uses the default Generator which uses normals provided by Xoroshiro128.

# As replacement for numpy.random
import randomgen.generator as random

Generator can also be used as a replacement for RandomState, although the random values are generated by Xoroshiro128. It also isn’t possible to directly seed a Generator.

# As replacement for RandomState()
from randomgen import Generator
rg = Generator()

Seeds can be passed to any of the bit generators. Here MT19937 is used and the Generator is accessed via the property generator.

from randomgen import MT19937
rg = MT19937(12345).generator


RandomGen takes a different approach to producing random numbers from the numpy.random.RandomState object used in NumPy. Random number generation is separated into two components, a bit generator and a random generator.

The bit generator has a limited set of responsibilities – it manages the underlying RNG state and provides functions to produce random doubles and random unsigned 32- and 64-bit values. The bit generator also handles all seeding since this varies when using alternative bit generators.

The random generator (Generator) takes the bit generator-provided functions and transforms them into more useful distributions, e.g., simulated normal random values. This structure allows alternative bit generators to be used without code duplication.

The Generator is the user-facing object that is nearly identical to RandomState. The canonical method to initialize a generator passes a bit generator – MT19937, the underlying RNG in NumPy – as the sole argument. Note that the bit generator must be instantized.

from randomgen import Generator, MT19937
rg = Generator(MT19937())

Seed information is directly passed to the bit generator.

rg = Generator(MT19937(12345))

A shorthand method is also available which uses the generator() property from a bit generator to access an embedded random generator.

rg = MT19937(12345).generator

What’s New or Different


The Box-Muller method used to produce NumPy’s normals is no longer available in Generator. It is not possible to reproduce the random values using Generator for the normal distribution or any other distribution that relies on the normal such as the gamma or student’s t. If you require backward compatibility, a legacy generator, RandomState, has been created which can fully reproduce the sequence produced by NumPy.

  • The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy’s Box-Muller or inverse CDF implementations.

  • Optional dtype argument that accepts np.float32 or np.float64 to produce either single or double prevision uniform random variables for select distributions

  • Optional out argument that allows existing arrays to be filled for select distributions

  • Simulate from the complex normal distribution (complex_normal())

  • random_entropy() provides access to the system source of randomness that is used in cryptographic applications (e.g., /dev/urandom on Unix).

  • All bit generators functions to produce doubles, uint64s and uint32s via CTypes (ctypes()) and CFFI (cffi()). This allows these bit generators to be used in numba.

  • The bit generators can be used in downstream projects via Cython.

  • Support for Lemire’s method [Lemire] of generating uniform integers on an arbitrary interval by setting use_masked=True in (integers()).

See What’s New or Different for a complete list of improvements and differences.

Parallel Generation

The included generators can be used in parallel, distributed applications in one of two ways:

Supported Generators

The main innovation is the inclusion of a number of alternative pseudo-random number generators, ‘in addition’ to the standard PRNG in NumPy. The included PRNGs are:

  • MT19937 - The standard NumPy generator. Produces identical results to NumPy using the same seed/state. Adds a jump function that advances the generator as-if 2**128 draws have been made (jumped()). See NumPy’s documentation.

  • dSFMT - SSE2 enabled versions of the MT19937 generator. Theoretically the same, but with a different state and so it is not possible to produce a sequence identical to MT19937. Supports jump and so can be used in parallel applications. See the dSFMT authors’ page.

  • XoroShiro128+ - Improved version of XorShift128+ with better performance and statistical quality. Like the XorShift generators, it can be jumped to produce multiple streams in parallel applications. See jumped() for details. More information about this PRNG is available at the xorshift, xoroshiro and xoshiro authors’ page.

  • XorShift1024*φ - Fast fast generator based on the XSadd generator. Supports jump and so can be used in parallel applications. See the documentation for jumped() for details. More information about these PRNGs is available at the xorshift, xoroshiro and xoshiro authors’ page.

  • Xorshiro256** and Xorshiro512** - The most recently introduced XOR, shift, and rotate generator. Supports jump and so can be used in parallel applications. See the documentation for jumped() for details. More information about these PRNGs is available at the xorshift, xoroshiro and xoshiro authors’ page.

  • PCG-64 - Fast generator that support many parallel streams and can be advanced by an arbitrary amount. See the documentation for advance(). PCG-64 has a period of \(2^{128}\). See the PCG author’s page for more details about this class of PRNG.

  • ThreeFry and Philox - counter-based generators capable of being advanced an arbitrary number of steps or generating independent streams. See the Random123 page for more details about this class of PRNG.

Bit Generators


These for formerly called Basic Random Number Generators. They have been renamed Bit Generators for compatibility with the version that will ship with NumPy.