ENH: use SeedSequence to generate entropy for seeding

1 files changed, 39 insertions, 28 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index a35ba4aaf..109302b7a 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
@@ -52,28 +56,37 @@ the random values are generated by `~PCG64`. 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
@@ -150,9 +163,14 @@ 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.
+* MT19937 - The standard Python BitGenerator. Adds a `~mt19937.MT19937.jumped`
+  function that returns a new generator with state as-if ``2**128`` draws have
+  been made.
+* PCG-64 - Fast generator that support many parallel streams and
+  can be advanced by an arbitrary amount. See the documentation for
+  :meth:`~.PCG64.advance`. PCG-64 has a period of
+  :math:`2^{128}`. See the `PCG author's page`_ for more details about
+  this class of PRNG.
 * 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
@@ -163,21 +181,14 @@ The included BitGenerators are:
 .. _`PCG author's page`: http://www.pcg-random.org/
 .. _`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
 --------