DOC: clean up for moved references, remove ISeedSequence

numpy · rgommers · Oct 17, 2019 · Sep 27, 2019 · Sep 28, 2019 · Sep 29, 2019
commit 185efe1bb746ad5b6ac23d106df12ad35a207d49
diff --git a/doc/source/reference/random/bit_generators/bitgenerators.rst b/doc/source/reference/random/bit_generators/bitgenerators.rst
diff --git a/doc/source/reference/random/bit_generators/index.rst b/doc/source/reference/random/bit_generators/index.rst
@@ -1,5 +1,3 @@
-.. _bit_generator:
-
 .. currentmodule:: numpy.random
 
 Bit Generators
@@ -35,14 +33,18 @@ The included BitGenerators are:
 .. _`Random123`: https://www.deshawresearch.com/resources_random123.html
 .. _`SFC author's page`: http://pracrand.sourceforge.net/RNG_engines.txt
 
+.. autosummary::
+   :toctree: generated/
+
+    BitGenerator
+
 .. toctree::
    :maxdepth: 1
 
-   BitGenerator <bitgenerators>
-   MT19937 <mt19937>
-   PCG64 <pcg64>
-   Philox <philox>
-   SFC64 <sfc64>
+    MT19937 <mt19937>
+    PCG64 <pcg64>
+    Philox <philox>
+    SFC64 <sfc64>
 
 Seeding and Entropy
 -------------------
@@ -53,7 +55,7 @@ seed. All of the provided BitGenerators will take an arbitrary-sized
 non-negative integer, or a list of such integers, as a seed. BitGenerators
 need to take those inputs and process them into a high-quality internal state
 for the BitGenerator. All of the BitGenerators in numpy delegate that task to
-`~SeedSequence`, which uses hashing techniques to ensure that even low-quality
+`SeedSequence`, which uses hashing techniques to ensure that even low-quality
 seeds generate high-quality initial states.
 
 .. code-block:: python
@@ -107,6 +109,3 @@ convenient ways.
    :toctree: generated/
 
     SeedSequence
-    _bit_generator.ISeedSequence
-    _bit_generator.ISpawnableSeedSequence
-    _bit_generator.SeedlessSeedSequence
diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
@@ -123,7 +123,7 @@ The `Generator` is the user-facing object that is nearly identical to
   rg.random()
 
 One can also instantiate `Generator` directly with a `BitGenerator` instance.
-To use the older `~mt19937.MT19937` algorithm, one can instantiate it directly
+To use the older `MT19937` algorithm, one can instantiate it directly
 and pass it to `Generator`.
 
 .. code-block:: python

diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
@@ -10,19 +10,20 @@ What's New or Different
   The Box-Muller method used to produce NumPy's normals is no longer available
   in `Generator`.  It is not possible to reproduce the exact random
   values using ``Generator`` for the normal distribution or any other
-  distribution that relies on the normal such as the `gamma` or
-  `standard_t`. If you require bitwise backward compatible
-  streams, use `RandomState`.
+  distribution that relies on the normal such as the `Generator.gamma` or
+  `Generator.standard_t`. If you require bitwise backward compatible
+  streams, use `RandomState`, i.e. `RandomState.gamma` or
+  `RandomState.standard_t`.
 
 Quick comparison of legacy `mtrand <legacy>`_ to the new `Generator`
 
 ================== ==================== =============
 Feature            Older Equivalent     Notes
 ------------------ -------------------- -------------
 `~.Generator`      `~.RandomState`      ``Generator`` requires a stream
-                                        source, called a `BitGenerator
-                                        <_bit_generators>` A number of these
-                                        are provided.  ``RandomState`` uses
+                                        source, called a `BitGenerator`
+                                        A number of these are provided.
+                                        ``RandomState`` uses
                                         the Mersenne Twister `~.MT19937` by
                                         default, but can also be instantiated
                                         with any BitGenerator.

diff --git a/doc/source/reference/random/parallel.rst b/doc/source/reference/random/parallel.rst
@@ -18,10 +18,10 @@ a `~BitGenerator`. It uses hashing techniques to ensure that low-quality seeds
 are turned into high quality initial states (at least, with very high
 probability).
 
-For example, `~mt19937.MT19937` has a state consisting of 624
+For example, `MT19937` has a state consisting of 624
 `uint32` integers. A naive way to take a 32-bit integer seed would be to just set
 the last element of the state to the 32-bit seed and leave the rest 0s. This is
-a valid state for `~mt19937.MT19937`, but not a good one. The Mersenne Twister
+a valid state for `MT19937`, but not a good one. The Mersenne Twister
 algorithm `suffers if there are too many 0s`_. Similarly, two adjacent 32-bit
 integer seeds (i.e. ``12345`` and ``12346``) would produce very similar
 streams.
@@ -91,15 +91,15 @@ territory ([2]_).
 .. [2] In this calculation, we can ignore the amount of numbers drawn from each
        stream. Each of the PRNGs we provide has some extra protection built in
        that avoids overlaps if the `~SeedSequence` pools differ in the
-       slightest bit. `~pcg64.PCG64` has :math:`2^{127}` separate cycles
+       slightest bit. `PCG64` has :math:`2^{127}` separate cycles
        determined by the seed in addition to the position in the
        :math:`2^{128}` long period for each cycle, so one has to both get on or
        near the same cycle *and* seed a nearby position in the cycle.
-       `~philox.Philox` has completely independent cycles determined by the seed.
-       `~sfc64.SFC64` incorporates a 64-bit counter so every unique seed is at
+       `Philox` has completely independent cycles determined by the seed.
+       `SFC64` incorporates a 64-bit counter so every unique seed is at
        least :math:`2^{64}` iterations away from any other seed. And
-       finally, `~mt19937.MT19937` has just an unimaginably huge period. Getting
-       a collision internal to `~SeedSequence` is the way a failure would be
+       finally, `MT19937` has just an unimaginably huge period. Getting
+       a collision internal to `SeedSequence` is the way a failure would be
        observed.
 
 .. _`implements an algorithm`: http://www.pcg-random.org/posts/developing-a-seed_seq-alternative.html
@@ -113,10 +113,10 @@ territory ([2]_).
 Independent Streams
 -------------------
 
-:class:`~philox.Philox` is a counter-based RNG based which generates values by
+`Philox` is a counter-based RNG based which generates values by
 encrypting an incrementing counter using weak cryptographic primitives. The
 seed determines the key that is used for the encryption. Unique keys create
-unique, independent streams. :class:`~philox.Philox` lets you bypass the
+unique, independent streams. `hilox` lets you bypass the
 seeding algorithm to directly set the 128-bit key. Similar, but different, keys
 will still create independent streams.
 

diff --git a/doc/source/reference/random/performance.rst b/doc/source/reference/random/performance.rst
@@ -5,21 +5,21 @@ Performance
 
 Recommendation
 **************
-The recommended generator for general use is :class:`~pcg64.PCG64`. It is
+The recommended generator for general use is `PCG64`. It is
 statistically high quality, full-featured, and fast on most platforms, but
 somewhat slow when compiled for 32-bit processes.
 
-:class:`~philox.Philox` is fairly slow, but its statistical properties have
+`Philox` is fairly slow, but its statistical properties have
 very high quality, and it is easy to get assuredly-independent stream by using
 unique keys. If that is the style you wish to use for parallel streams, or you
 are porting from another system that uses that style, then
-:class:`~philox.Philox` is your choice.
+`Philox` is your choice.
 
-:class:`~sfc64.SFC64` is statistically high quality and very fast. However, it
+`SFC64` is statistically high quality and very fast. However, it
 lacks jumpability. If you are not using that capability and want lots of speed,
 even on 32-bit processes, this is your choice.
 
-:class:`~mt19937.MT19937` `fails some statistical tests`_ and is not especially
+`MT19937` `fails some statistical tests`_ and is not especially
 fast compared to modern PRNGs. For these reasons, we mostly do not recommend
 using it on its own, only through the legacy `~.RandomState` for
 reproducing old results. That said, it has a very long history as a default in
@@ -31,20 +31,20 @@ Timings
 *******
 
 The timings below are the time in ns to produce 1 random value from a
-specific distribution.  The original :class:`~mt19937.MT19937` generator is
+specific distribution.  The original `MT19937` generator is
 much slower since it requires 2 32-bit values to equal the output of the
 faster generators.
 
 Integer performance has a similar ordering.
 
 The pattern is similar for other, more complex generators. The normal
-performance of the legacy :class:`~.RandomState` generator is much
+performance of the legacy `RandomState` generator is much
 lower than the other since it uses the Box-Muller transformation rather
 than the Ziggurat generator. The performance gap for Exponentials is also
 large due to the cost of computing the log function to invert the CDF.
 The column labeled MT19973 is used the same 32-bit generator as
-:class:`~.RandomState` but produces random values using
-:class:`~Generator`.
+`RandomState` but produces random values using
+`Generator`.
 
 .. csv-table::
     :header: ,MT19937,PCG64,Philox,SFC64,RandomState
@@ -61,7 +61,7 @@ The column labeled MT19973 is used the same 32-bit generator as
     Poissons,67.6,52.4,69.2,46.4,78.1
 
 The next table presents the performance in percentage relative to values
-generated by the legacy generator, `RandomState(MT19937())`. The overall
+generated by the legacy generator, ``RandomState(MT19937())``. The overall
 performance was computed using a geometric mean.
 
 .. csv-table::

diff --git a/doc/source/release/1.17.0-notes.rst b/doc/source/release/1.17.0-notes.rst
@@ -239,7 +239,7 @@ New extensible `numpy.random` module with selectable random number generators
 -----------------------------------------------------------------------------
 A new extensible `numpy.random` module along with four selectable random number
 generators and improved seeding designed for use in parallel processes has been
-added. The currently available :ref:`Bit Generators <bit_generator>` are
+added. The currently available `Bit Generators` are
 `~mt19937.MT19937`, `~pcg64.PCG64`, `~philox.Philox`, and `~sfc64.SFC64`.
 ``PCG64`` is the new default while ``MT19937`` is retained for backwards
 compatibility. Note that the legacy random module is unchanged and is now

diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
@@ -206,8 +206,8 @@ of elements that we want, instead of the step::
     `empty_like`,
     `arange`,
     `linspace`,
-    `numpy.random.mtrand.RandomState.rand`,
-    `numpy.random.mtrand.RandomState.randn`,
+    `numpy.random.RandomState.rand`,
+    `numpy.random.RandomState.randn`,
     `fromfunction`,
     `fromfile`
 

diff --git a/numpy/matlib.py b/numpy/matlib.py
@@ -239,7 +239,7 @@ def rand(*args):
 
     See Also
     --------
-    randn, numpy.random.rand
+    randn, numpy.random.RandomState.rand
 
     Examples
     --------
@@ -285,7 +285,7 @@ def randn(*args):
 
     See Also
     --------
-    rand, random.randn
+    rand, random.RandomState.randn
 
     Notes
     -----

diff --git a/numpy/random/__init__.py b/numpy/random/__init__.py
@@ -183,15 +183,15 @@
 from . import _bounded_integers
 
 from ._generator import Generator, default_rng
-from ._bit_generator import SeedSequence
+from ._bit_generator import SeedSequence, BitGenerator
 from ._mt19937 import MT19937
 from ._pcg64 import PCG64
 from ._philox import Philox
 from ._sfc64 import SFC64
 from .mtrand import *
 
 __all__ += ['Generator', 'RandomState', 'SeedSequence', 'MT19937',
-            'Philox', 'PCG64', 'SFC64', 'default_rng']
+            'Philox', 'PCG64', 'SFC64', 'default_rng', 'BitGenerator']
 
 
 def __RandomState_ctor():

diff --git a/numpy/random/_bit_generator.pyx b/numpy/random/_bit_generator.pyx
@@ -482,13 +482,12 @@ cdef class BitGenerator():
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence}, optional
+    seed : {None, int, array_like[ints], SeedSequence}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
-        `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        ~`numpy.randomSeedSequence` to derive the initial `BitGenerator` state.
+        One may also pass in a ~`numpy.random.SeedSequence` instance.
 
     Attributes
     ----------

diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx
@@ -4097,19 +4097,18 @@ def default_rng(seed=None):
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence, BitGenerator, Generator}, optional
+    seed : {None, int, array_like[ints], SeedSequence, BitGenerator, Generator}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
         `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        pass in a`SeedSequence` instance
         Additionally, when passed a `BitGenerator`, it will be wrapped by
         `Generator`. If passed a `Generator`, it will be returned unaltered.
 
     Notes
     -----
-    When `seed` is omitted or ``None``, a new `BitGenerator` and `Generator` will
+    When ``seed`` is omitted or ``None``, a new `BitGenerator` and `Generator` will
     be instantiated each time. This function does not manage a default global
     instance.
     """

diff --git a/numpy/random/_mt19937.pyx b/numpy/random/_mt19937.pyx
@@ -48,13 +48,12 @@ cdef class MT19937(BitGenerator):
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence}, optional
+    seed : {None, int, array_like[ints], SeedSequence}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
         `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        pass in a `SeedSequence` instance.
 
     Attributes
     ----------

diff --git a/numpy/random/_pcg64.pyx b/numpy/random/_pcg64.pyx
@@ -44,13 +44,12 @@ cdef class PCG64(BitGenerator):
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence}, optional
+    seed : {None, int, array_like[ints], SeedSequence}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
         `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        pass in a `SeedSequence` instance.
 
     Notes
     -----

diff --git a/numpy/random/_philox.pyx b/numpy/random/_philox.pyx
@@ -64,21 +64,20 @@ cdef class Philox(BitGenerator):
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence}, optional
+    seed : {None, int, array_like[ints], SeedSequence}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
         `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        pass in a `SeedSequence` instance.
     counter : {None, int, array_like}, optional
         Counter to use in the Philox state. Can be either
         a Python int (long in 2.x) in [0, 2**256) or a 4-element uint64 array.
         If not provided, the RNG is initialized at 0.
     key : {None, int, array_like}, optional
-        Key to use in the Philox state.  Unlike seed, the value in key is
+        Key to use in the Philox state.  Unlike ``seed``, the value in key is
         directly set. Can be either a Python int in [0, 2**128) or a 2-element
-        uint64 array. `key` and `seed` cannot both be used.
+        uint64 array. `key` and ``seed`` cannot both be used.
 
     Attributes
     ----------
@@ -110,10 +109,10 @@ cdef class Philox(BitGenerator):
     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
+    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
+    Alternately, one can omit the ``seed`` parameter and set the ``key`` and
     ``counter`` directly.
 
     **Parallel Features**
@@ -148,7 +147,7 @@ cdef class Philox(BitGenerator):
 
     **Compatibility Guarantee**
 
-    ``Philox`` makes a guarantee that a fixed seed will always produce
+    ``Philox`` makes a guarantee that a fixed ``seed`` will always produce
     the same random integer stream.
 
     Examples

diff --git a/numpy/random/_sfc64.pyx b/numpy/random/_sfc64.pyx
@@ -39,13 +39,12 @@ cdef class SFC64(BitGenerator):
 
     Parameters
     ----------
-    seed : {None, int, array_like[ints], ISeedSequence}, optional
+    seed : {None, int, array_like[ints], SeedSequence}, optional
         A seed to initialize the `BitGenerator`. If None, then fresh,
         unpredictable entropy will be pulled from the OS. If an ``int`` or
         ``array_like[ints]`` is passed, then it will be passed to
         `SeedSequence` to derive the initial `BitGenerator` state. One may also
-        pass in an implementor of the `ISeedSequence` interface like
-        `SeedSequence`.
+        pass in a `SeedSequence` instance.
 
     Notes
     -----