DOC: np.random documentation cleanup and expansion.

5 files changed, 48 insertions, 29 deletions

diff --git a/numpy/random/bit_generator.pyx b/numpy/random/bit_generator.pyx
index c4f35ca31..8886d2e05 100644
--- a/numpy/random/bit_generator.pyx
+++ b/numpy/random/bit_generator.pyx
@@ -174,7 +174,10 @@ cdef uint32_t mix(uint32_t x, uint32_t y):
 
 class ISeedSequence(abc.ABC):
     """
-    ISeedSequence() is the abstract base class for SeedSequences.
+    Abstract base class for seed sequences.
+
+    ``BitGenerator`` implementations should treat any object that adheres to
+    this interface as a seed sequence.
 
     See Also
     --------
@@ -208,6 +211,9 @@ class ISeedSequence(abc.ABC):
 
 
 class ISpawnableSeedSequence(ISeedSequence):
+    """
+    Abstract base class for seed sequences that can spawn.
+    """
 
     @abc.abstractmethod
     def spawn(self, n_children):
@@ -229,7 +235,7 @@ class ISpawnableSeedSequence(ISeedSequence):
 
 cdef class SeedlessSeedSequence():
     """
-    SeedlessSeedSequence() is used for BitGenerators with no need for seed state.
+    A seed sequence for BitGenerators with no need for seed state.
 
     See Also
     --------
diff --git a/numpy/random/mt19937.pyx b/numpy/random/mt19937.pyx
index 409ad336e..db571cbef 100644
--- a/numpy/random/mt19937.pyx
+++ b/numpy/random/mt19937.pyx
@@ -74,16 +74,12 @@ cdef class MT19937(BitGenerator):
 
     **State and Seeding**
 
-    The ``MT19937`` state vector consists of a 768-element array of
-    32-bit unsigned integers plus a single integer value between 0 and 768
+    The ``MT19937`` state vector consists of a 624-element array of
+    32-bit unsigned integers plus a single integer value between 0 and 624
     that indexes the current position within the main array.
 
-    ``MT19937`` is seeded using either a single 32-bit unsigned integer
-    or a vector of 32-bit unsigned integers.  In either case, the input seed is
-    used as an input (or inputs) for a hashing function, and the output of the
-    hashing function is used as the initial state. Using a single 32-bit value
-    for the seed can only initialize a small range of the possible initial
-    state values.
+    The input seed is processed by `SeedSequence` to fill the whole state. The
+    first element is reset such that only its most significant bit is set.
 
     **Parallel Features**
 
diff --git a/numpy/random/pcg64.pyx b/numpy/random/pcg64.pyx
index 891045230..53ac21bf8 100644
--- a/numpy/random/pcg64.pyx
+++ b/numpy/random/pcg64.pyx
@@ -59,18 +59,19 @@ cdef class PCG64(BitGenerator):
     directly consumable in Python and must be consumed by a ``Generator``
     or similar object that supports low-level access.
 
-    Supports the method advance to advance the RNG an arbitrary number of
+    Supports the method :meth:`advance` to advance the RNG an arbitrary number of
     steps. The state of the PCG-64 RNG is represented by 2 128-bit unsigned
     integers.
 
-    See ``PCG32`` for a similar implementation with a smaller period.
-
     **State and Seeding**
 
     The ``PCG64`` state vector consists of 2 unsigned 128-bit values,
-    which are represented externally as Python ints.
-    ``PCG64`` is seeded using a single 128-bit unsigned integer.
-    In addition, a second 128-bit unsigned integer is used to set the stream.
+    which are represented externally as Python ints. One is the state of the
+    PRNG, which is advanced by a linear congruential generator (LCG). The
+    second is a fixed odd increment used in the LCG.
+
+    The input seed is processed by `SeedSequence` to generate both values. The
+    increment is not independently settable.
 
     **Parallel Features**
 
diff --git a/numpy/random/philox.pyx b/numpy/random/philox.pyx
index 1224bf89e..1594242d8 100644
--- a/numpy/random/philox.pyx
+++ b/numpy/random/philox.pyx
@@ -99,21 +99,28 @@ cdef class Philox(BitGenerator):
 
     **State and Seeding**
 
-    The ``Philox`` state vector consists of a 2 256-bit values encoded as
-    4-element uint64 arrays. One is a counter which is incremented by 1 for
-    every 4 64-bit randoms produced.  The second is a key which determined
-    the sequence produced.  Using different keys produces independent
-    sequences.
-
-    ``Philox`` is seeded using either a single 64-bit unsigned integer
-    or a vector of 64-bit unsigned integers.  In either case, the seed is
-    used as an input for a second random number generator,
-    SplitMix64, and the output of this PRNG function is used as the initial state.
-    Using a single 64-bit value for the seed can only initialize a small range of
-    the possible initial state values.
+    The ``Philox`` state vector consists of a 256-bit value encoded as
+    a 4-element uint64 array and a 128-bit value encoded as a 2-element uint64
+    array. The former is a counter which is incremented by 1 for every 4 64-bit
+    randoms produced. The second is a key which determined the sequence
+    produced. Using different keys produces independent sequences.
+
+    The input seed is processed by `SeedSequence` to generate the key. The
+    counter is set to 0.
+
+    Alternately, one can omit the seed parameter and set the ``key`` and
+    ``counter`` directly.
 
     **Parallel Features**
 
+    The preferred way to use a BitGenerator in parallel applications is to use
+    the `SeedSequence.spawn` method to obtain entropy values, and to use these
+    to generate new BitGenerators:
+
+    >>> from numpy.random import Generator, Philox, SeedSequence
+    >>> sg = SeedSequence(1234)
+    >>> rg = [Generator(Philox(s)) for s in sg.spawn(10)]
+
     ``Philox`` can be used in parallel applications by calling the ``jumped``
     method  to advances the state as-if :math:`2^{128}` random numbers have
     been generated. Alternatively, ``advance`` can be used to advance the
diff --git a/numpy/random/sfc64.pyx b/numpy/random/sfc64.pyx
index 2c3ec4767..74a07da73 100644
--- a/numpy/random/sfc64.pyx
+++ b/numpy/random/sfc64.pyx
@@ -50,13 +50,22 @@ cdef class SFC64(BitGenerator):
     on, depending on the seed; the expected period will be about
     :math:`2^{255}` ([2]_). ``SFC64`` incorporates a 64-bit counter which means
     that the absolute minimum cycle length is :math:`2^{64}` and that distinct
-    seeds will not run into each other for at least :math:`2**{64}` iterations.
+    seeds will not run into each other for at least :math:`2^{64}` iterations.
 
     ``SFC64`` provides a capsule containing function pointers that produce
     doubles, and unsigned 32 and 64- bit integers. These are not
     directly consumable in Python and must be consumed by a ``Generator``
     or similar object that supports low-level access.
 
+    **State and Seeding**
+
+    The ``SFC64`` state vector consists of 4 unsigned 64-bit values. The last
+    is a 64-bit counter that increments by 1 each iteration.
+
+    The input seed is processed by `SeedSequence` to generate the first
+    3 values, then the ``SFC64`` algorithm is iterated a small number of times
+    to mix.
+
     **Compatibility Guarantee**
 
     ``SFC64`` makes a guarantee that a fixed seed will always produce the same