DOC: move all new-or-different info to its own page.

2 files changed, 30 insertions, 105 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index f62347cfe..10ab7bd46 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -123,7 +123,8 @@ For backward compatibility, we still maintain the legacy `RandomState` class.
 It continues to use the `~MT19937` algorithm by default, and old seeds continue
 to reproduce the same results. The convenience :ref:`functions-in-numpy-random`
 are still aliases to the methods on a single global `RandomState` instance. See
-:ref:`legacy` for the complete details.
+:ref:`legacy` for the complete details. See :ref:`new-or-different` for
+a detailed comparison between `Generator` and `RandomState`.
 
 Parallel Generation
 ~~~~~~~~~~~~~~~~~~~
@@ -139,82 +140,6 @@ a number of ways:
 Users with a very large amount of parallelism will want to consult
 :ref:`upgrading-pcg64`.
 
-What's New or Different
-~~~~~~~~~~~~~~~~~~~~~~~
-.. warning::
-
-  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 `RandomState.gamma` or
-  `RandomState.standard_t`. If you require bitwise backward compatible
-  streams, use `RandomState`.
-
-`Generator` can be used as a replacement for `RandomState`. Both class
-instances hold an internal `BitGenerator` instance to provide the bit
-stream, it is accessible as ``gen.bit_generator``. Some long-overdue API
-cleanup means that legacy and compatibility methods have been removed from
-`Generator`.
-
-=================== ============== ============
-`RandomState`       `Generator`    Notes
-------------------- -------------- ------------
-``random_sample``,  ``random``     Compatible with `random.random`
-``rand``
-------------------- -------------- ------------
-``randint``,        ``integers``   Add an ``endpoint`` kwarg
-``random_integers``
-------------------- -------------- ------------
-``tomaxint``        removed        Use ``integers(0, np.iinfo(np.int_).max,``
-                                   ``endpoint=False)``
-------------------- -------------- ------------
-``seed``            removed        Use `SeedSequence.spawn`
-=================== ============== ============
-
-Something like the following code can be used to support both ``RandomState``
-and ``Generator``, with the understanding that the interfaces are slightly
-different.
-
-.. code-block:: python
-
-    try:
-        rng_integers = rng.integers
-    except AttributeError:
-        rng_integers = rng.randint
-    a = rng_integers(1000)
-
-* The Generator's normal, exponential and gamma functions use 256-step Ziggurat
-  methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
-  implementations.
-* Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64``
-  to produce either single or double precision uniform random variables for
-  select distributions
-* Optional ``out`` argument that allows existing arrays to be filled for
-  select distributions
-* All BitGenerators can produce doubles, uint64s and uint32s via CTypes
-  (`PCG64.ctypes`) and CFFI (`PCG64.cffi`). This allows the bit generators
-  to be used in numba.
-* The bit generators can be used in downstream projects via
-  :ref:`Cython <random_cython>`.
-* `Generator.integers` is now the canonical way to generate integer
-  random numbers from a discrete uniform distribution. The ``rand`` and
-  ``randn`` methods are only available through the legacy `RandomState`.
-  The ``endpoint`` keyword can be used to specify open or closed intervals.
-  This replaces both ``randint`` and the deprecated ``random_integers``.
-* `Generator.random` is now the canonical way to generate floating-point
-  random numbers, which replaces `RandomState.random_sample`,
-  `RandomState.sample`, and `RandomState.ranf`. This is consistent with
-  Python's `random.random`.
-* All BitGenerators in numpy use `SeedSequence` to convert seeds into
-  initialized states.
-* The addition of an ``axis`` keyword argument to methods such as 
-  `Generator.choice`, `Generator.permutation`,  and `Generator.shuffle` 
-  improves support for sampling from and shuffling multi-dimensional arrays.
-
-See :ref:`new-or-different` for a complete list of improvements and
-differences from the traditional ``Randomstate``.
-
-
 Concepts
 --------
 .. toctree::
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index 8f4a70540..3c443025c 100644
--- a/doc/source/reference/random/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -5,17 +5,9 @@
 What's New or Different
 -----------------------
 
-.. warning::
-
-  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 `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 :ref:`mtrand <legacy>` to the new `Generator`
+NumPy 1.17.0 introduced `Generator` as an improved replacement for
+the :ref:`legacy <legacy>` `RandomState`. Here is a quick comparison of the two
+implementations.
 
 ================== ==================== =============
 Feature            Older Equivalent     Notes
@@ -44,21 +36,17 @@ Feature            Older Equivalent     Notes
                                         ``high`` interval endpoint
 ================== ==================== =============
 
-And in more detail:
-
-* Simulate from the complex normal distribution
-  (`~.Generator.complex_normal`)
 * The normal, exponential and gamma generators use 256-step Ziggurat
   methods which are 2-10 times faster than NumPy's default implementation in
   `~.Generator.standard_normal`, `~.Generator.standard_exponential` or
-  `~.Generator.standard_gamma`.
-
+  `~.Generator.standard_gamma`. Because of the change in algorithms, it is not
+  possible to reproduce the exact random values using ``Generator`` for these
+  distributions or any distribution method that relies on them.
 
 .. ipython:: python
 
-  from  numpy.random import Generator, PCG64
   import numpy.random
-  rng = Generator(PCG64())
+  rng = np.random.default_rng()
   %timeit -n 1 rng.standard_normal(100000)
   %timeit -n 1 numpy.random.standard_normal(100000)
 
@@ -74,18 +62,25 @@ And in more detail:
 
 
 * `~.Generator.integers` is now the canonical way to generate integer
-  random numbers from a discrete uniform distribution. The ``rand`` and
-  ``randn`` methods are only available through the legacy `~.RandomState`.
-  This replaces both ``randint`` and the deprecated ``random_integers``.
-* The Box-Muller method used to produce NumPy's normals is no longer available.
+  random numbers from a discrete uniform distribution. This replaces both
+  ``randint`` and the deprecated ``random_integers``.
+*  The ``rand`` and ``randn`` methods are only available through the legacy
+  `~.RandomState`.
+* `Generator.random` is now the canonical way to generate floating-point
+  random numbers, which replaces `RandomState.random_sample`,
+  `RandomState.sample`, and `RandomState.ranf`. This is consistent with
+  Python's `random.random`.
 * All bit generators can produce doubles, uint64s and
   uint32s via CTypes (`~PCG64.ctypes`) and CFFI (`~PCG64.cffi`).
   This allows these bit generators to be used in numba.
 * The bit generators can be used in downstream projects via
   Cython.
+* All bit generators use `SeedSequence` to :ref:`convert seed integers to
+  initialized states <seeding-and-entropy>`.
 * Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64``
   to produce either single or double precision uniform random variables for
-  select distributions
+  select distributions. `~.Generator.integers` accepts a ``dtype`` argument
+  with any signed or unsigned integer dtype.
 
   * Uniforms (`~.Generator.random` and `~.Generator.integers`)
   * Normals (`~.Generator.standard_normal`)
@@ -94,9 +89,10 @@ And in more detail:
 
 .. ipython:: python
 
-  rng = Generator(PCG64(0))
-  rng.random(3, dtype='d')
-  rng.random(3, dtype='f')
+  rng = np.random.default_rng()
+  rng.random(3, dtype=np.float64)
+  rng.random(3, dtype=np.float32)
+  rng.integers(0, 256, size=3, dtype=np.uint8)
 
 * Optional ``out`` argument that allows existing arrays to be filled for
   select distributions
@@ -111,6 +107,7 @@ And in more detail:
 
 .. ipython:: python
 
+  rng = np.random.default_rng()
   existing = np.zeros(4)
   rng.random(out=existing[:2])
   print(existing)
@@ -121,9 +118,12 @@ And in more detail:
 
 .. ipython:: python
 
-  rng = Generator(PCG64(123456789))
+  rng = np.random.default_rng()
   a = np.arange(12).reshape((3, 4))
   a
   rng.choice(a, axis=1, size=5)
   rng.shuffle(a, axis=1)        # Shuffle in-place
   a
+
+* Added a method to sample from the complex normal distribution
+  (`~.Generator.complex_normal`)