randomstate’s documentation

This package contains drop-in replacements for the NumPy RandomState object that change the core random number generator.

What’s New or Different

In [1]: from randomstate.prng.xoroshiro128plus import standard_normal

In [2]: %timeit standard_normal(1000000, method='bm')
   ...: %timeit standard_normal(1000000, method='zig')
   ...: 
42.1 ms +- 108 us per loop (mean +- std. dev. of 7 runs, 10 loops each)
9.78 ms +- 68.4 us per loop (mean +- std. dev. of 7 runs, 100 loops each)
In [4]: from randomstate.prng.xoroshiro128plus import standard_exponential

In [5]: %timeit standard_exponential(1000000, method='inv')
   ...: %timeit standard_exponential(1000000, method='zig')
   ...: 
56 ms +- 562 us per loop (mean +- std. dev. of 7 runs, 10 loops each)
5.41 ms +- 87.9 us per loop (mean +- std. dev. of 7 runs, 100 loops each)
In [7]: from randomstate.prng.xoroshiro128plus import standard_gamma

In [8]: %timeit standard_gamma(3.0, 1000000, method='inv')
   ...: %timeit standard_gamma(3.0, 1000000, method='zig')
   ...: 
57.9 ms +- 863 us per loop (mean +- std. dev. of 7 runs, 10 loops each)
27.9 ms +- 904 us per loop (mean +- std. dev. of 7 runs, 10 loops each)
In [10]: import randomstate as rs

In [11]: rs.seed(0)

In [12]: rs.random_sample(3, dtype='d')
Out[12]: array([ 0.5488135 ,  0.71518937,  0.60276338])

In [13]: rs.seed(0)

In [14]: rs.random_sample(3, dtype='f')
Out[14]: array([ 0.54881346,  0.59284461,  0.71518934], dtype=float32)
In [15]: import numpy as np

In [16]: import randomstate as rs

In [17]: existing = np.zeros(4)

In [18]: rs.seed(0)

In [19]: rs.random_sample(out=existing[:2])
Out[19]: array([ 0.5488135 ,  0.71518937])

In [20]: print(existing)
[ 0.5488135   0.71518937  0.          0.        ]
  • For changes since the previous release, see the Change Log

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 (randomstate.prng.mt19937.jump()). See NumPy’s documentation.
  • SFMT and 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. Both generators support 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 randomstate.prng.xoroshiro128plus.jump() for details. More information about this PRNG is available at the xorshift and xoroshiro authors’ page.
  • XorShit128+ and XorShift1024* - Vast fast generators based on the XSadd generator. These generators support jump and so can be used in parallel applications. See the documentation for randomstate.prng.xorshift1024.jump() for details. More information about these PRNGs is available at the xorshift and xoroshiro authors’ page.
  • PCG-32 and PCG-64 - Fast generators that support many parallel streams and can be advanced by an arbitrary amount. See the documentation for randomstate.prng.pcg64.advance(). PCG-32 only as a period of \(2^{64}\) while PCG-64 has a period of \(2^{128}\). See the PCG author’s page for more details about this class of PRNG.
  • Multiplicative Lagged Fibonacci Generator MLFG(1279, 861, *) - A directly implemented multiplicative lagged Fibonacci generator with a very large period and good performance. Future plans include multiple stream support. See the wiki page on Fibonacci generators.
  • MRG32K3A - a classic and popular generator by L’Ecuyer. Future plans include multiple stream support. See the MRG32K3A author’s page. Lower performance than more modern generators.

Indices and tables