The Generator provides access to a wide range of distributions, and served as a replacement for RandomState. The main difference between the two is that Generator relies on an additional BitGenerator to manage state and generate the random bits, which are then transformed into random values from useful distributions. The default BitGenerator used by Generator is PCG64. The BitGenerator can be changed by passing an instantized BitGenerator to Generator.
Generator
RandomState
PCG64
numpy.random.
default_rng
Construct a new Generator with the default BitGenerator (PCG64).
A seed to initialize the BitGenerator. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int or array_like[ints] is passed, then it will be passed to SeedSequence to derive the initial BitGenerator state. One may also pass in a SeedSequence instance. Additionally, when passed a BitGenerator, it will be wrapped by Generator. If passed a Generator, it will be returned unaltered.
BitGenerator
int
array_like[ints]
SeedSequence
The initialized generator object.
Notes
If seed is not a BitGenerator or a Generator, a new BitGenerator is instantiated. This function does not manage a default global instance.
seed
Examples
default_rng is the reccomended constructor for the random number class Generator. Here are several ways we can construct a random number generator using default_rng and the Generator class.
Here we use default_rng to generate a random float:
>>> import numpy as np >>> rng = np.random.default_rng(12345) >>> print(rng) Generator(PCG64) >>> rfloat = rng.random() >>> rfloat 0.22733602246716966 >>> type(rfloat) <class 'float'>
Here we use default_rng to generate 3 random integers between 0 (inclusive) and 10 (exclusive):
>>> import numpy as np >>> rng = np.random.default_rng(12345) >>> rints = rng.integers(low=0, high=10, size=3) >>> rints array([6, 2, 7]) >>> type(rints[0]) <class 'numpy.int64'>
Here we specify a seed so that we have reproducible results:
>>> import numpy as np >>> rng = np.random.default_rng(seed=42) >>> print(rng) Generator(PCG64) >>> arr1 = rng.random((3, 3)) >>> arr1 array([[0.77395605, 0.43887844, 0.85859792], [0.69736803, 0.09417735, 0.97562235], [0.7611397 , 0.78606431, 0.12811363]])
If we exit and restart our Python interpreter, we’ll see that we generate the same random numbers again:
>>> import numpy as np >>> rng = np.random.default_rng(seed=42) >>> arr2 = rng.random((3, 3)) >>> arr2 array([[0.77395605, 0.43887844, 0.85859792], [0.69736803, 0.09417735, 0.97562235], [0.7611397 , 0.78606431, 0.12811363]])
Container for the BitGenerators.
Generator exposes a number of methods for generating random numbers drawn from a variety of probability distributions. In addition to the distribution-specific arguments, each method takes a keyword argument size that defaults to None. If size is None, then a single value is generated and returned. If size is an integer, then a 1-D array filled with generated values is returned. If size is a tuple, then an array with that shape is filled and returned.
None
The function numpy.random.default_rng will instantiate a Generator with numpy’s default BitGenerator.
numpy.random.default_rng
No Compatibility Guarantee
Generator does not provide a version compatibility guarantee. In particular, as better algorithms evolve the bit stream may change.
BitGenerator to use as the core generator.
See also
Recommended constructor for Generator.
The Python stdlib module random contains pseudo-random number generator with a number of methods that are similar to the ones available in Generator. It uses Mersenne Twister, and this bit generator can be accessed using MT19937. Generator, besides being NumPy-aware, has the advantage that it provides a much larger number of probability distributions to choose from.
random
MT19937
>>> from numpy.random import Generator, PCG64 >>> rg = Generator(PCG64()) >>> rg.standard_normal() -0.203 # random
bit_generator
Gets the bit generator instance used by the generator
integers(low[, high, size, dtype, endpoint])
integers
Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive).
random([size, dtype, out])
Return random floats in the half-open interval [0.0, 1.0).
choice(a[, size, replace, p, axis, shuffle])
choice
Generates a random sample from a given 1-D array
bytes(length)
bytes
Return random bytes.
The methods for randomly permuting a sequence are
shuffle(x[, axis])
shuffle
Modify an array or sequence in-place by shuffling its contents.
permutation(x[, axis])
permutation
Randomly permute a sequence, or return a permuted range.
permuted(x[, axis, out])
permuted
Randomly permute x along axis axis.
The following table summarizes the behaviors of the methods.
method
copy/in-place
axis handling
in-place
as if 1d
copy
either (use ‘out’ for in-place)
axis independent
The following subsections provide more details about the differences.
The main difference between Generator.shuffle and Generator.permutation is that Generator.shuffle operates in-place, while Generator.permutation returns a copy.
Generator.shuffle
Generator.permutation
By default, Generator.permuted returns a copy. To operate in-place with Generator.permuted, pass the same array as the first argument and as the value of the out parameter. For example,
Generator.permuted
out
>>> rg = np.random.default_rng() >>> x = np.arange(0, 15).reshape(3, 5) >>> x array([[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14]]) >>> y = rg.permuted(x, axis=1, out=x) >>> x array([[ 1, 0, 2, 4, 3], # random [ 6, 7, 8, 9, 5], [10, 14, 11, 13, 12]])
Note that when out is given, the return value is out:
>>> y is x True
axis
An important distinction for these methods is how they handle the axis parameter. Both Generator.shuffle and Generator.permutation treat the input as a one-dimensional sequence, and the axis parameter determines which dimension of the input array to use as the sequence. In the case of a two-dimensional array, axis=0 will, in effect, rearrange the rows of the array, and axis=1 will rearrange the columns. For example
axis=0
axis=1
>>> rg = np.random.default_rng() >>> x = np.arange(0, 15).reshape(3, 5) >>> x array([[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14]]) >>> rg.permutation(x, axis=1) array([[ 1, 3, 2, 0, 4], # random [ 6, 8, 7, 5, 9], [11, 13, 12, 10, 14]])
Note that the columns have been rearranged “in bulk”: the values within each column have not changed.
The method Generator.permuted treats the axis parameter similar to how numpy.sort treats it. Each slice along the given axis is shuffled independently of the others. Compare the following example of the use of Generator.permuted to the above example of Generator.permutation:
numpy.sort
>>> rg.permuted(x, axis=1) array([[ 1, 0, 2, 4, 3], # random [ 5, 7, 6, 9, 8], [10, 14, 12, 13, 11]])
In this example, the values within each row (i.e. the values along axis=1) have been shuffled independently. This is not a “bulk” shuffle of the columns.
Generator.shuffle works on non-NumPy sequences. That is, if it is given a sequence that is not a NumPy array, it shuffles that sequence in-place. For example,
>>> rg = np.random.default_rng() >>> a = ['A', 'B', 'C', 'D', 'E'] >>> rg.shuffle(a) # shuffle the list in-place >>> a ['B', 'D', 'A', 'E', 'C'] # random
beta(a, b[, size])
beta
Draw samples from a Beta distribution.
binomial(n, p[, size])
binomial
Draw samples from a binomial distribution.
chisquare(df[, size])
chisquare
Draw samples from a chi-square distribution.
dirichlet(alpha[, size])
dirichlet
Draw samples from the Dirichlet distribution.
exponential([scale, size])
exponential
Draw samples from an exponential distribution.
f(dfnum, dfden[, size])
f
Draw samples from an F distribution.
gamma(shape[, scale, size])
gamma
Draw samples from a Gamma distribution.
geometric(p[, size])
geometric
Draw samples from the geometric distribution.
gumbel([loc, scale, size])
gumbel
Draw samples from a Gumbel distribution.
hypergeometric(ngood, nbad, nsample[, size])
hypergeometric
Draw samples from a Hypergeometric distribution.
laplace([loc, scale, size])
laplace
Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
logistic([loc, scale, size])
logistic
Draw samples from a logistic distribution.
lognormal([mean, sigma, size])
lognormal
Draw samples from a log-normal distribution.
logseries(p[, size])
logseries
Draw samples from a logarithmic series distribution.
multinomial(n, pvals[, size])
multinomial
Draw samples from a multinomial distribution.
multivariate_hypergeometric(colors, nsample)
multivariate_hypergeometric
Generate variates from a multivariate hypergeometric distribution.
multivariate_normal(mean, cov[, size, …])
multivariate_normal
Draw random samples from a multivariate normal distribution.
negative_binomial(n, p[, size])
negative_binomial
Draw samples from a negative binomial distribution.
noncentral_chisquare(df, nonc[, size])
noncentral_chisquare
Draw samples from a noncentral chi-square distribution.
noncentral_f(dfnum, dfden, nonc[, size])
noncentral_f
Draw samples from the noncentral F distribution.
normal([loc, scale, size])
normal
Draw random samples from a normal (Gaussian) distribution.
pareto(a[, size])
pareto
Draw samples from a Pareto II or Lomax distribution with specified shape.
poisson([lam, size])
poisson
Draw samples from a Poisson distribution.
power(a[, size])
power
Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
rayleigh([scale, size])
rayleigh
Draw samples from a Rayleigh distribution.
standard_cauchy([size])
standard_cauchy
Draw samples from a standard Cauchy distribution with mode = 0.
standard_exponential([size, dtype, method, out])
standard_exponential
Draw samples from the standard exponential distribution.
standard_gamma(shape[, size, dtype, out])
standard_gamma
Draw samples from a standard Gamma distribution.
standard_normal([size, dtype, out])
standard_normal
Draw samples from a standard Normal distribution (mean=0, stdev=1).
standard_t(df[, size])
standard_t
Draw samples from a standard Student’s t distribution with df degrees of freedom.
triangular(left, mode, right[, size])
triangular
Draw samples from the triangular distribution over the interval [left, right].
[left, right]
uniform([low, high, size])
uniform
Draw samples from a uniform distribution.
vonmises(mu, kappa[, size])
vonmises
Draw samples from a von Mises distribution.
wald(mean, scale[, size])
wald
Draw samples from a Wald, or inverse Gaussian, distribution.
weibull(a[, size])
weibull
Draw samples from a Weibull distribution.
zipf(a[, size])
zipf
Draw samples from a Zipf distribution.
numpy.random