Random Generator — NumPy v2.3.dev0 Manual (original) (raw)
The Generator provides access to a wide range of distributions, and served as a replacement forRandomState. 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 byGenerator 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, RandomState}, optional
A seed to initialize the BitGenerator. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int orarray_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 byGenerator. If passed a Generator, it will be returned unaltered. When passed a legacy RandomState instance it will be coerced to a Generator.
Returns:
Generator
The initialized generator object.
Notes
If seed is not a BitGenerator or a Generator, a new BitGeneratoris 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 classGenerator. 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.
See also
Recommended constructor for Generator.
Notes
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.
Examples
from numpy.random import Generator, PCG64 rng = Generator(PCG64()) rng.standard_normal() -0.203 # random
Accessing the BitGenerator and spawning#
Simple random data#
Permutations#
The methods for randomly permuting a sequence are
The following table summarizes the behaviors of the methods.
The following subsections provide more details about the differences.
In-place vs. copy#
The main difference between Generator.shuffle and Generator.permutationis that Generator.shuffle operates in-place, while Generator.permutationreturns a copy.
By default, Generator.permuted returns a copy. To operate in-place withGenerator.permuted, pass the same array as the first argument and as the value of the out parameter. For example,
import numpy as np 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:
Handling the axis parameter#
An important distinction for these methods is how they handle the axisparameter. 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
import numpy as np 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 ofGenerator.permuted to the above example of Generator.permutation:
import numpy as np rng = np.random.default_rng() 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 alongaxis=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.
import numpy as np 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