What’s New or Different

Quick comparison of legacy mtrand to the new Generator

And in more detail:

• Simulate from the complex normal distribution (complex_normal)
• The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy’s default implementation in standard_normal, standard_exponential or standard_gamma.

In [1]: from  numpy.random import Generator, PCG64

In [2]: import numpy.random

In [3]: rng = Generator(PCG64())

In [4]: %timeit -n 1 rng.standard_normal(100000)
   ...: %timeit -n 1 numpy.random.standard_normal(100000)
   ...: 
1.11 ms +- 23.8 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
1.97 ms +- 23.8 us per loop (mean +- std. dev. of 7 runs, 1 loop each)

In [5]: %timeit -n 1 rng.standard_exponential(100000)
   ...: %timeit -n 1 numpy.random.standard_exponential(100000)
   ...: 
603 us +- 11.4 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
1.45 ms +- 15.6 us per loop (mean +- std. dev. of 7 runs, 1 loop each)

In [6]: %timeit -n 1 rng.standard_gamma(3.0, 100000)
   ...: %timeit -n 1 numpy.random.standard_gamma(3.0, 100000)
   ...: 
2.16 ms +- 22.8 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
4.07 ms +- 15.4 us per loop (mean +- std. dev. of 7 runs, 1 loop each)

• integers is now the canonical way to generate integer random numbers from a discrete uniform distribution. The rand and randn methods are only available through the legacy RandomState. This replaces both randint and the deprecated random_integers.
• The Box-Muller method used to produce NumPy’s normals is no longer available.
• All bit generators can 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.

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

  • Uniforms (random and integers)
  • Normals (standard_normal)
  • Standard Gammas (standard_gamma)
  • Standard Exponentials (standard_exponential)

In [7]: rng = Generator(PCG64(0))

In [8]: rng.random(3, dtype='d')
Out[8]: array([0.63696169, 0.26978671, 0.04097352])

In [9]: rng.random(3, dtype='f')
Out[9]: array([0.07524014, 0.01652759, 0.17526728], dtype=float32)

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

  • Uniforms (random)
  • Normals (standard_normal)
  • Standard Gammas (standard_gamma)
  • Standard Exponentials (standard_exponential)

  This allows multithreading to fill large arrays in chunks using suitable BitGenerators in parallel.

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

In [11]: rng.random(out=existing[:2])
Out[11]: array([0.91275558, 0.60663578])

In [12]: print(existing)
[0.91275558 0.60663578 0.         0.        ]

• Optional axis argument for methods like choice, permutation and shuffle that controls which axis an operation is performed over for multi-dimensional arrays.

In [13]: rng = Generator(PCG64(123456789))

In [14]: a = np.arange(12).reshape((3, 4))

In [15]: a
Out[15]: 
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])

In [16]: rng.choice(a, axis=1, size=5)
Out[16]: 
array([[ 3,  0,  2,  3,  1],
       [ 7,  4,  6,  7,  5],
       [11,  8, 10, 11,  9]])

In [17]: rng.shuffle(a, axis=1)        # Shuffle in-place

In [18]: a
Out[18]: 
array([[ 3,  1,  2,  0],
       [ 7,  5,  6,  4],
       [11,  9, 10,  8]])