Quick start#

Thenumpy.random module implements pseudo-random number generators(PRNGs or RNGs, for short) with the ability to draw samples from a variety ofprobability distributions. In general, users will create aGenerator instancewithdefault_rng and call the various methods on it to obtain samples fromdifferent distributions.

>>>importnumpyasnp>>>rng=np.random.default_rng()

>>>rng.random()0.06369197489564249  # may vary

>>>rng.standard_normal(10)array([-0.31018314, -1.8922078 , -0.3628523 , -0.63526532,  0.43181166,  # may vary        0.51640373,  1.25693945,  0.07779185,  0.84090247, -2.13406828])

>>>rng.integers(low=0,high=10,size=5)array([8, 7, 6, 2, 0])  # may vary

Our RNGs are deterministic sequences and can be reproduced by specifying a seed integer toderive its initial state. By default, with no seed provided,default_rng willseed the RNG from nondeterministic data from the operating system and thereforegenerate different numbers each time. The pseudo-random sequences will beindependent for all practical purposes, at least those purposes for which ourpseudo-randomness was good for in the first place.

>>>importnumpyasnp>>>rng1=np.random.default_rng()>>>rng1.random()0.6596288841243357  # may vary>>>rng2=np.random.default_rng()>>>rng2.random()0.11885628817151628  # may vary

Seeds should be large positive integers.default_rng can take positiveintegers of any size. We recommend using very large, unique numbers to ensurethat your seed is different from anyone else’s. This is good practice to ensurethat your results are statistically independent from theirs unless you areintentionallytrying to reproduce their result. A convenient way to getsuch a seed number is to usesecrets.randbits to get anarbitrary 128-bit integer.

>>>importnumpyasnp>>>importsecrets>>>secrets.randbits(128)122807528840384100672342137672332424406  # may vary>>>rng1=np.random.default_rng(122807528840384100672342137672332424406)>>>rng1.random()0.5363922081269535>>>rng2=np.random.default_rng(122807528840384100672342137672332424406)>>>rng2.random()0.5363922081269535

See the documentation ondefault_rng andSeedSequence for more advancedoptions for controlling the seed in specialized scenarios.

Generator and its associated infrastructure was introduced in NumPy version1.17.0. There is still a lot of code that uses the olderRandomState and thefunctions innumpy.random. While there are no plans to remove them at thistime, we do recommend transitioning toGenerator as you can. The algorithmsare faster, more flexible, and will receive more improvements in the future.For the most part,Generator can be used as a replacement forRandomState.SeeLegacy random generation for information on the legacy infrastructure,What’s new or different for information on transitioning, andNEP 19 for some of the reasoning for the transition.

Design#

Users primarily interact withGenerator instances. EachGenerator instanceowns aBitGenerator instance that implements the core RNG algorithm. TheBitGenerator has a limited set of responsibilities. It manages state andprovides functions to produce random doubles and random unsigned 32- and 64-bitvalues.

TheGenerator takes the bit generator-provided stream and transforms theminto more useful distributions, e.g., simulated normal random values. Thisstructure allows alternative bit generators to be used with little codeduplication.

NumPy implements several differentBitGenerator classes implementingdifferent RNG algorithms.default_rng currently usesPCG64 as thedefaultBitGenerator. It has better statistical properties and performancethan theMT19937 algorithm used in the legacyRandomState. SeeBit generators for more details on the supported BitGenerators.

default_rng and BitGenerators delegate the conversion of seeds into RNGstates toSeedSequence internally.SeedSequence implements a sophisticatedalgorithm that intermediates between the user’s input and the internalimplementation details of eachBitGenerator algorithm, each of which canrequire different amounts of bits for its state. Importantly, it lets you usearbitrary-sized integers and arbitrary sequences of such integers to mixtogether into the RNG state. This is a useful primitive for constructingaflexible pattern for parallel RNG streams.

For backward compatibility, we still maintain the legacyRandomState class.It continues to use theMT19937 algorithm by default, and old seeds continueto reproduce the same results. The convenienceFunctions in numpy.randomare still aliases to the methods on a single globalRandomState instance. SeeLegacy random generation for the complete details. SeeWhat’s new or different fora detailed comparison betweenGenerator andRandomState.

Concepts#

Features#