diff options
Diffstat (limited to 'doc/source/reference/random/index.rst')
| -rw-r--r-- | doc/source/reference/random/index.rst | 92 |
1 files changed, 36 insertions, 56 deletions
diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index 3159f0e1c..f32853e7c 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -9,6 +9,10 @@ Numpy's random number routines produce pseudo random numbers using combinations of a `BitGenerator` to create sequences and a `Generator` to use those sequences to sample from different statistical distributions: +* SeedSequence: Objects that provide entropy for the initial state of a + BitGenerator. A good SeedSequence will provide initializations across the + entire range of possible states for the BitGenerator, otherwise biases may + creep into the generated bit streams. * BitGenerators: Objects that generate random numbers. These are typically unsigned integer words filled with sequences of either 32 or 64 random bits. * Generators: Objects that transform sequences of random bits from a @@ -30,8 +34,8 @@ instance's methods are imported into the numpy.random namespace, see Quick Start ----------- -By default, `Generator` uses normals provided by `xoshiro256.Xoshiro256` -which will be faster than the legacy methods in `RandomState` +By default, `Generator` uses normals provided by `PCG64` which will be +statistically more reliable than the legacy methods in `RandomState` .. code-block:: python @@ -40,7 +44,7 @@ which will be faster than the legacy methods in `RandomState` random.standard_normal() `Generator` can be used as a direct replacement for `~RandomState`, although -the random values are generated by `~xoshiro256.Xoshiro256`. The +the random values are generated by `~PCG64`. The `Generator` holds an instance of a BitGenerator. It is accessible as ``gen.bit_generator``. @@ -52,28 +56,37 @@ the random values are generated by `~xoshiro256.Xoshiro256`. The rg.standard_normal() rg.bit_generator - -Seeds can be passed to any of the BitGenerators. Here `mt19937.MT19937` is used -and is the wrapped with a `~.Generator`. - +Seeds can be passed to any of the BitGenerators. The provided value is mixed +via `~.SeedSequence` to spread a possible sequence of seeds across a wider +range of initialization states for the BitGenerator. Here `~.PCG64` is used and +is wrapped with a `~.Generator`. .. code-block:: python - from numpy.random import Generator, MT19937 - rg = Generator(MT19937(12345)) + from numpy.random import Generator, PCG64 + rg = Generator(PCG64(12345)) rg.standard_normal() - Introduction ------------ RandomGen takes a different approach to producing random numbers from the -`RandomState` object. Random number generation is separated into two -components, a bit generator and a random generator. +`RandomState` object. Random number generation is separated into three +components, a seed sequence, a bit generator and a random generator. -The bit generator has a limited set of responsibilities. It manages state +The `BitGenerator` has a limited set of responsibilities. It manages state and provides functions to produce random doubles and random unsigned 32- and -64-bit values. The bit generator also handles all seeding which varies with -different bit generators. +64-bit values. + +The `SeedSequence` takes a seed and provides the initial state for the +`BitGenerator`. Since consecutive seeds can cause bad effects when comparing +`BitGenerator` streams, the `SeedSequence` uses current best-practice methods +to spread the initial state out. However small seeds may still be unable to +reach all possible initialization states, which can cause biases among an +ensemble of small-seed runs. For many cases, that doesn't matter. If you just +want to hold things in place while you debug something, biases aren't a +concern. For actual simulations whose results you care about, let +``SeedSequence(None)`` do its thing and then log/print the +`SeedSequence.entropy` for repeatable `BitGenerator` streams. The `random generator <Generator>` takes the bit generator-provided stream and transforms them into more useful @@ -86,15 +99,15 @@ The `Generator` is the user-facing object that is nearly identical to the sole argument. Note that the BitGenerator must be instantiated. .. code-block:: python - from numpy.random import Generator, MT19937 - rg = Generator(MT19937()) + from numpy.random import Generator, PCG64 + rg = Generator(PCG64()) rg.random() Seed information is directly passed to the bit generator. .. code-block:: python - rg = Generator(MT19937(12345)) + rg = Generator(PCG64(12345)) rg.random() What's New or Different @@ -120,8 +133,8 @@ What's New or Different source of randomness that is used in cryptographic applications (e.g., ``/dev/urandom`` on Unix). * All BitGenerators can produce doubles, uint64s and uint32s via CTypes - (`~xoshiro256.Xoshiro256.ctypes`) and CFFI - (:meth:`~xoshiro256.Xoshiro256.cffi`). This allows the bit generators to + (`~PCG64.ctypes`) and CFFI + (:meth:`~PCG64.cffi`). This allows the bit generators to be used in numba. * The bit generators can be used in downstream projects via :ref:`Cython <randomgen_cython>`. @@ -146,47 +159,14 @@ one of two ways: * :ref:`independent-streams` * :ref:`jump-and-advance` -Supported BitGenerators ------------------------ -The included BitGenerators are: - -* MT19937 - The standard Python BitGenerator. Produces identical results to - Python using the same seed/state. Adds a `~mt19937.MT19937.jumped` function - that returns a new generator with state as-if ``2**128`` draws have been made. -* dSFMT - SSE2 enabled versions of the MT19937 generator. Theoretically - the same, but with a different state and so it is not possible to produce a - sequence identical to MT19937. Supports ``jumped`` and so can - be used in parallel applications. See the `dSFMT authors' page`_. -* Xorshiro256** and Xorshiro512** - The most recently introduced XOR, - shift, and rotate generator. Supports ``jumped`` and so can be used in - parallel applications. See the documentation for - `~xoshiro256.Xoshirt256.jumped` for details. More information about these bit - generators is available at the `xorshift, xoroshiro and xoshiro authors' - page`_. -* ThreeFry and Philox - counter-based generators capable of being advanced an - arbitrary number of steps or generating independent streams. See the - `Random123`_ page for more details about this class of bit generators. - -.. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/ -.. _`PCG author's page`: http://www.pcg-random.org/ -.. _`xorshift, xoroshiro and xoshiro authors' page`: http://xoroshiro.di.unimi.it/ -.. _`Random123`: https://www.deshawresearch.com/resources_random123.html - -Generator ---------- +Concepts +-------- .. toctree:: :maxdepth: 1 generator legacy mtrand <legacy> - -BitGenerators -------------- - -.. toctree:: - :maxdepth: 1 - - BitGenerators <bit_generators/index> + BitGenerators, SeedSequences <bit_generators/index> Features -------- |