Random `Generator`#

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.

numpy.random.default_rng(seed=None)#

Construct a new Generator with the default BitGenerator (PCG64).

Parameters:

seed{None, int, array_like[ints], SeedSequence, BitGenerator, Generator}, optional: 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 all values must be non-negative and 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.

Returns:

Generator: 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.

See Seeding and entropy for more information about seeding.

Examples

default_rng is the recommended 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]])

class numpy.random.Generator(bit_generator)#

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.

The function numpy.random.default_rng will instantiate a Generator with numpy’s default BitGenerator.

No Compatibility Guarantee

Generator does not provide a version compatibility guarantee. In particular, as better algorithms evolve the bit stream may change.

Parameters:

bit_generatorBitGenerator: BitGenerator to use as the core generator.

Accessing the BitGenerator and spawning#

`bit_generator`	Gets the bit generator instance used by the generator
`spawn`(n_children)	Create new independent child generators.

Simple random data#

`integers`(low[, high, size, dtype, endpoint])	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])	Generates a random sample from a given array
`bytes`(length)	Return random bytes.

Permutations#

The methods for randomly permuting a sequence are

`shuffle`(x[, axis])	Modify an array or sequence in-place by shuffling its contents.
`permutation`(x[, axis])	Randomly permute a sequence, or return a permuted range.
`permuted`(x[, axis, out])	Randomly permute x along axis axis.

The following table summarizes the behaviors of the methods.

method	copy/in-place	axis handling
shuffle	in-place	as if 1d
permutation	copy	as if 1d
permuted	either (use ‘out’ for in-place)	axis independent

The following subsections provide more details about the differences.

In-place vs. copy#

The main difference between Generator.shuffle and Generator.permutation is that Generator.shuffle operates in-place, while Generator.permutation returns a copy.

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,

>>> rng = 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 = rng.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

Handling the `axis` parameter#

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

>>> rng = 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]])
>>> rng.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:

>>> rng.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.

Shuffling non-NumPy sequences#

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,

>>> rng = np.random.default_rng()
>>> a = ['A', 'B', 'C', 'D', 'E']
>>> rng.shuffle(a)  # shuffle the list in-place
>>> a 
['B', 'D', 'A', 'E', 'C']  # random

Distributions#

`beta`(a, b[, size])	Draw samples from a Beta distribution.
`binomial`(n, p[, size])	Draw samples from a binomial distribution.
`chisquare`(df[, size])	Draw samples from a chi-square distribution.
`dirichlet`(alpha[, size])	Draw samples from the Dirichlet distribution.
`exponential`([scale, size])	Draw samples from an exponential distribution.
`f`(dfnum, dfden[, size])	Draw samples from an F distribution.
`gamma`(shape[, scale, size])	Draw samples from a Gamma distribution.
`geometric`(p[, size])	Draw samples from the geometric distribution.
`gumbel`([loc, scale, size])	Draw samples from a Gumbel distribution.
`hypergeometric`(ngood, nbad, nsample[, size])	Draw samples from a Hypergeometric distribution.
`laplace`([loc, scale, size])	Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
`logistic`([loc, scale, size])	Draw samples from a logistic distribution.
`lognormal`([mean, sigma, size])	Draw samples from a log-normal distribution.
`logseries`(p[, size])	Draw samples from a logarithmic series distribution.
`multinomial`(n, pvals[, size])	Draw samples from a multinomial distribution.
`multivariate_hypergeometric`(colors, nsample)	Generate variates from a multivariate hypergeometric distribution.
`multivariate_normal`(mean, cov[, size, ...])	Draw random samples from a multivariate normal distribution.
`negative_binomial`(n, p[, size])	Draw samples from a negative binomial distribution.
`noncentral_chisquare`(df, nonc[, size])	Draw samples from a noncentral chi-square distribution.
`noncentral_f`(dfnum, dfden, nonc[, size])	Draw samples from the noncentral F distribution.
`normal`([loc, scale, size])	Draw random samples from a normal (Gaussian) distribution.
`pareto`(a[, size])	Draw samples from a Pareto II (AKA Lomax) distribution with specified shape.
`poisson`([lam, size])	Draw samples from a Poisson distribution.
`power`(a[, size])	Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
`rayleigh`([scale, size])	Draw samples from a Rayleigh distribution.
`standard_cauchy`([size])	Draw samples from a standard Cauchy distribution with mode = 0.
`standard_exponential`([size, dtype, method, out])	Draw samples from the standard exponential distribution.
`standard_gamma`(shape[, size, dtype, out])	Draw samples from a standard Gamma distribution.
`standard_normal`([size, dtype, out])	Draw samples from a standard Normal distribution (mean=0, stdev=1).
`standard_t`(df[, size])	Draw samples from a standard Student's t distribution with df degrees of freedom.
`triangular`(left, mode, right[, size])	Draw samples from the triangular distribution over the interval `[left, right]`.
`uniform`([low, high, size])	Draw samples from a uniform distribution.
`vonmises`(mu, kappa[, size])	Draw samples from a von Mises distribution.
`wald`(mean, scale[, size])	Draw samples from a Wald, or inverse Gaussian, distribution.
`weibull`(a[, size])	Draw samples from a Weibull distribution.
`zipf`(a[, size])	Draw samples from a Zipf distribution.

Random Generator#