What’s new or different#
NumPy 1.17.0 introduced Generator
as an improved replacement for
the legacy RandomState
. Here is a quick comparison of the two
implementations.
Feature |
Older Equivalent |
Notes |
|
||
Access the values in a
BitGenerator, convert them to
Many other distributions are also supported. |
||
Use the |
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
orstandard_gamma
. Because of the change in algorithms, it is not possible to reproduce the exact random values usingGenerator
for these distributions or any distribution method that relies on them.
In [1]: import numpy.random
In [2]: rng = np.random.default_rng()
In [3]: %timeit -n 1 rng.standard_normal(100000)
...: %timeit -n 1 numpy.random.standard_normal(100000)
...:
455 us +- 17.1 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
1.3 ms +- 17.8 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
In [4]: %timeit -n 1 rng.standard_exponential(100000)
...: %timeit -n 1 numpy.random.standard_exponential(100000)
...:
458 us +- 1.49 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
1.03 ms +- 5.38 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
In [5]: %timeit -n 1 rng.standard_gamma(3.0, 100000)
...: %timeit -n 1 numpy.random.standard_gamma(3.0, 100000)
...:
1.15 ms +- 15.2 us per loop (mean +- std. dev. of 7 runs, 1 loop each)
2.26 ms +- 14.9 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. This replaces bothrandint
and the deprecatedrandom_integers
.The
rand
andrandn
methods are only available through the legacyRandomState
.Generator.random
is now the canonical way to generate floating-point random numbers, which replacesRandomState.random_sample
,sample
, andranf
, all of which were aliases. This is consistent with Python’srandom.random
.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.
All bit generators use
SeedSequence
to convert seed integers to initialized states.Optional
dtype
argument that acceptsnp.float32
ornp.float64
to produce either single or double precision uniform random variables for select distributions.integers
accepts adtype
argument with any signed or unsigned integer dtype.Normals (
standard_normal
)Standard Gammas (
standard_gamma
)Standard Exponentials (
standard_exponential
)
In [6]: rng = np.random.default_rng()
In [7]: rng.random(3, dtype=np.float64)
Out[7]: array([0.38384469, 0.708575 , 0.56572287])
In [8]: rng.random(3, dtype=np.float32)
Out[8]: array([0.23382288, 0.1098206 , 0.317388 ], dtype=float32)
In [9]: rng.integers(0, 256, size=3, dtype=np.uint8)
Out[9]: array([ 34, 243, 94], dtype=uint8)
Optional
out
argument that allows existing arrays to be filled for select distributionsUniforms (
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]: rng = np.random.default_rng()
In [11]: existing = np.zeros(4)
In [12]: rng.random(out=existing[:2])
Out[12]: array([0.7476536 , 0.21406269])
In [13]: print(existing)
[0.7476536 0.21406269 0. 0. ]
Optional
axis
argument for methods likechoice
,permutation
andshuffle
that controls which axis an operation is performed over for multi-dimensional arrays.
In [14]: rng = np.random.default_rng()
In [15]: a = np.arange(12).reshape((3, 4))
In [16]: a
Out[16]:
array([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
In [17]: rng.choice(a, axis=1, size=5)
Out[17]:
array([[ 1, 2, 0, 3, 1],
[ 5, 6, 4, 7, 5],
[ 9, 10, 8, 11, 9]])
In [18]: rng.shuffle(a, axis=1) # Shuffle in-place
In [19]: a
Out[19]:
array([[ 2, 0, 3, 1],
[ 6, 4, 7, 5],
[10, 8, 11, 9]])
Added a method to sample from the complex normal distribution (complex_normal)