DOC: tighten up documentation, add a table of comparison

1 files changed, 100 insertions, 31 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index 3c9160fb1..701415920 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -3,28 +3,64 @@
 numpy.random
 ============
 
+<<<<<<< HEAD
 A `~RandomGenerator` can
 be initialized with a number of different Random Number Generators (RNG)s, and
 exposes many different probability distributions.
 
+=======
+Numpy's random number routines produce psuedo random numbers using
+combinations of a `BitGenerator` to create sequences and a `Generator`
+to use those sequences to sample from different statistical distributions:
+
+* 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
+  BitGenerator into sequences of numbers that follow a specific probability
+  distribution (such as uniform, Normal or Binomial) within a specified
+  interval.
+
+Since Numpy version 1.17.0 the Generator can be initialized with a
+number of different BitGenerators. It exposes many different probability
+distributions. See `NEP 19 <https://www.numpy.org/neps/
+nep-0019-rng-policy.html>`_ for context on the updated random Numpy number
+routines. The legacy `RandomState` random number routines are still
+available, but limited to a single BitGenerator.
+
+For convenience and backward compatibility, a single `RandomState`
+instance's methods are imported into the numpy.random namespace, see
+:ref:`legacy` for the complete list.
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 Quick Start
 -----------
 
+<<<<<<< HEAD
 By default, `RandomGenerator` uses normals provided by
 `xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in
 `mtrand.RandomState`
+=======
+By default, `Generator` uses normals provided by `xoroshiro128.Xoroshiro128`
+which will be faster than the legacy methods in `RandomState`
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 .. code-block:: python
 
-  # As replacement for numpy.random.RandomState
+  # Uses the old numpy.random.RandomState
   from numpy import random
   random.standard_normal()
 
+<<<<<<< HEAD
 `RandomGenerator` can be used as a direct replacement for
 `~RandomState`, although the random values are generated by
 `~xoroshiro128.Xoroshiro128`. The `RandomGenerator` holds an instance of a RNG.
 It is accessable as ``gen.brng``.
+=======
+`Generator` can be used as a direct replacement for `RandomState`,
+although the random values are generated by `~xoroshiro128.Xoroshiro128`. The
+`Generator` holds an instance of a BitGenerator. It is accessable as
+``gen.bit_generator``.
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 .. code-block:: python
 
@@ -32,6 +68,7 @@ It is accessable as ``gen.brng``.
   from numpy.random import RandomGenerator
   rg = RandomGenerator()
   rg.standard_normal()
+  rg.bit_generator
 
 
 Seeds can be passed to any of the basic RNGs. Here `mt19937.MT19937` is used
@@ -48,19 +85,30 @@ generator`.
 Introduction
 ------------
 RandomGen takes a different approach to producing random numbers from the
+<<<<<<< HEAD
 :class:`numpy.random.RandomState` object.  Random number generation is
 separated into two components, a basic RNG and a random generator.
+=======
+`RandomState` object.  Random number generation is separated into two
+components, a bit generator and a random generator.
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 The basic RNG has a limited set of responsibilities. It manages the
 underlying RNG state and provides functions to produce random doubles and
 random unsigned 32- and 64-bit values. The basic random generator also handles
 all seeding since this varies when using alternative basic RNGs.
 
+<<<<<<< HEAD
 The `random generator <~RandomGenerator>` takes the
 basic RNG-provided functions and transforms them into more useful
+=======
+The `random generator <Generator>` takes the
+bit generator-provided stream and transforms them into more useful
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 distributions, e.g., simulated normal random values. This structure allows
 alternative basic RNGs to be used without code duplication.
 
+<<<<<<< HEAD
 The ``RandomGenerator`` is the user-facing object
 that is nearly identical to :class:`~.RandomState`. The canonical
 method to initialize a generator passes a basic RNG -- `~mt19937.MT19937`, the
@@ -74,6 +122,12 @@ be instantized.
   rg.random_sample()
 
 Seed information is directly passed to the basic RNG.
+=======
+The `Generator` is the user-facing object that is nearly identical to
+`RandomState`. The canonical method to initialize a generator passes a
+`~mt19937.MT19937` bit generator, the underlying bit generator in Python -- as
+the sole argument. Note that the bit generator must be instantiated.
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 .. code-block:: python
 
@@ -93,13 +147,18 @@ What's New or Different
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  in `~RandomGenerator`.  It is not possible to reproduce the random values
-  using ``RandomGenerator`` for the normal distribution or any other
-  distribution that relies on the normal such as the gamma or student's t.
-  Use the backward-compatible legacy generator, `~mtrand`, which fully
-  reproduces the sequence produced by pre-1.17.0.
-
-* The normal, exponential and gamma generators use 256-step Ziggurat
+<<<<<<< HEAD
+  in `~.RandomGenerator`.  It is not possible to reproduce the exact random
+  values using ``RandomGenerator`` for the normal distribution or any other
+=======
+  in `Generator`.  It is not possible to reproduce the exact random
+  values using Generator for the normal distribution or any other
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
+  distribution that relies on the normal such as the `numpy.random.gamma` or
+  `numpy.random.standard_t`. If you require bitwise backward compatible
+  streams, use `RandomState`.
+
+* 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``
@@ -110,6 +169,7 @@ What's New or Different
 * `~entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
+<<<<<<< HEAD
 * All basic random generators functions can produce doubles, uint64s and
   uint32s via CTypes (`~xoroshiro128.Xoroshiro128.ctypes`)
   and CFFI (:meth:`~xoroshiro128.Xoroshiro128.cffi`).
@@ -119,7 +179,23 @@ What's New or Different
 * Support for Lemire’s method [Lemire]_ of generating uniform integers on an
   arbitrary interval by setting ``use_masked=True`` in
   `~RandomGenerator.randint`.
+=======
+* All BitGenerators can produce doubles, uint64s and uint32s via CTypes
+  (`~xoroshiro128.Xoroshiro128.ctypes`) and CFFI
+  (:meth:`~xoroshiro128.Xoroshiro128.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>`.
+* `~.Generator.integers` is now the canonical way to generate integer
+  random numbers from a discrete uniform distribution. The ``rand`` and
+  ``randn`` methods are only availabe 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 `random_sample`, `sample`, and `ranf`. This
+  is consistent with Python's `random.random`.
 
+>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
 
 See :ref:`new-or-different` for a complete list of improvements and
 differences.
@@ -133,15 +209,13 @@ one of two ways:
 * :ref:`independent-streams`
 * :ref:`jump-and-advance`
 
-Supported Generators
---------------------
-The main innovation is the inclusion of a number of alternative pseudo-random number
-generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are:
+Supported BitGenerators
+-----------------------
+The included BitGenerators are:
 
-* MT19937 - The standard NumPy generator.  Produces identical results to NumPy
-  using the same seed/state. Adds a
-  `~mt19937.MT19937.jump` function that advances the
-  generator as-if ``2**128`` draws have been made.  See `numpy.random`.
+* 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 ``jump`` and so can
@@ -155,20 +229,15 @@ generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are
 * XorShift1024*φ - Fast fast generator based on the XSadd
   generator. Supports ``jump`` and so can be used in
   parallel applications. See the documentation for
-  `~xorshift1024.Xorshift1024.jump` for details. More
-  information about these PRNGs is available at the
+  `~xorshift1024.Xorshift1024.jumped` for details. More
+  information about these bit generators is available at the
   `xorshift, xoroshiro and xoshiro authors' page`_.
 * Xorshiro256** and Xorshiro512** - The most recently introduced XOR,
   shift, and rotate generator. Supports ``jump`` and so can be used in
   parallel applications. See the documentation for
-  `~xoshiro256starstar.Xoshirt256StarStar.jump` for
-  details. More information about these PRNGs is available at the
-  `xorshift, xoroshiro and xoshiro authors' page`_.
-* PCG-64 - Fast generator that support many parallel streams and
-  can be advanced by an arbitrary amount. See the documentation for
-  `~pcg64.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.
+  `~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 PRNG.
@@ -178,21 +247,21 @@ generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are
 .. _`PCG author's page`: http://www.pcg-random.org/
 .. _`Random123`: https://www.deshawresearch.com/resources_random123.html
 
-Random Generator
-----------------
+Generator
+---------
 .. toctree::
    :maxdepth: 1
 
    generator
    legacy mtrand <legacy>
 
-Basic Random Number Generators
-------------------------------
+BitGenerators
+-------------
 
 .. toctree::
    :maxdepth: 1
 
-   Basic Random Number Generators <brng/index>
+   BitGenerators <bit_generators/index>
 
 New Features
 ------------