This is documentation for an old release of NumPy (version 1.17). Read this page in the documentation of the latest stable release (version 2.2).
What’s New or Different¶
Warning
The Box-Muller method used to produce NumPy’s normals is no longer available
in Generator
. It is not possible to reproduce the exact random
values using Generator
for the normal distribution or any other
distribution that relies on the normal such as the gamma
or
standard_t
. If you require bitwise backward compatible
streams, use RandomState
.
Quick comparison of legacy mtrand to the new Generator
Feature | Older Equivalent | Notes |
Generator |
RandomState |
Generator requires a stream
source, called a BitGenerator A number of these
are provided. RandomState uses
the Mersenne Twister MT19937 by
default, but can also be instantiated
with any BitGenerator. |
random |
random_sample ,
rand |
Access the values in a BitGenerator,
convert them to Many other distributions are also supported. |
integers |
randint ,
random_integers |
Use the endpoint kwarg to adjust
the inclusion or exclution of the
high interval endpoint |
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
orstandard_gamma
. integers
is now the canonical way to generate integer random numbers from a discrete uniform distribution. Therand
andrandn
methods are only available through the legacyRandomState
. This replaces bothrandint
and the deprecatedrandom_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.
In [1]: from numpy.random import Generator, PCG64
In [2]: import numpy.random
In [3]: rg = Generator(PCG64())
In [4]: %timeit rg.standard_normal(100000)
...: %timeit numpy.random.standard_normal(100000)
...:
871 us +- 7.51 us per loop (mean +- std. dev. of 7 runs, 1000 loops each)
2.06 ms +- 49.9 us per loop (mean +- std. dev. of 7 runs, 100 loops each)
In [5]: %timeit rg.standard_exponential(100000)
...: %timeit numpy.random.standard_exponential(100000)
...:
451 us +- 1.87 us per loop (mean +- std. dev. of 7 runs, 1000 loops each)
1.43 ms +- 15.5 us per loop (mean +- std. dev. of 7 runs, 1000 loops each)
In [6]: %timeit rg.standard_gamma(3.0, 100000)
...: %timeit numpy.random.standard_gamma(3.0, 100000)
...:
2.01 ms +- 11.4 us per loop (mean +- std. dev. of 7 runs, 100 loops each)
3.72 ms +- 19.9 us per loop (mean +- std. dev. of 7 runs, 100 loops each)
- Optional
dtype
argument that acceptsnp.float32
ornp.float64
to produce either single or double prevision uniform random variables for select distributions- Uniforms (
random
andintegers
) - Normals (
standard_normal
) - Standard Gammas (
standard_gamma
) - Standard Exponentials (
standard_exponential
)
- Uniforms (
In [7]: rg = Generator(PCG64(0))
In [8]: rg.random(3, dtype='d')
Out[8]: array([0.63696169, 0.26978671, 0.04097352])
In [9]: rg.random(3, dtype='f')
Out[9]: array([0.07524014, 0.01652753, 0.17526722], 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.
- Uniforms (
In [10]: existing = np.zeros(4)
In [11]: rg.random(out=existing[:2])
Out[11]: array([0.91275558, 0.60663578])
In [12]: print(existing)
[0.91275558 0.60663578 0. 0. ]