mattip · bashtage · Apr 19, 2019
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
@@ -43,21 +43,11 @@ And in more detail:
 * `~.entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
-* Simulate from the complex normal distribution
-  (`~.RandomGenerator.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
   `~.RandomGenerator.standard_normal`,
   `~.RandomGenerator.standard_exponential` or
   `~.RandomGenerator.standard_gamma`.
-* The Box-Muller used to produce NumPy's normals is no longer available.
-* All basic random generators functions to produce doubles, uint64s and
-  uint32s via CTypes (`~.xoroshiro128.Xoroshiro128.
-  ctypes`) and CFFI (`~.xoroshiro128.Xoroshiro128.cffi`).
-  This allows these basic RNGs to be used in numba.
-* The basic random number generators can be used in downstream projects via
-  Cython.
-
 
 .. ipython:: python
 
@@ -77,6 +67,14 @@ And in more detail:
   %timeit rg.standard_gamma(3.0, 100000)
   %timeit numpy.random.standard_gamma(3.0, 100000)
 
+
+* The Box-Muller used to produce NumPy's normals is no longer available.
+* All basic random generators functions to produce doubles, uint64s and
+  uint32s via CTypes (:meth:`~.xoroshiro128.Xoroshiro128.ctypes`)
+  and CFFI (:meth:`~.xoroshiro128.Xoroshiro128.cffi`).  This allows
+  the basic RNGs to be used in numba or in other low-level applications
+* The basic random number generators can be used in downstream projects via
+  Cython.
 * Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64``
   to produce either single or double prevision uniform random variables for
   select distributions
@@ -112,7 +110,7 @@ And in more detail:
   rg.random_sample(out=existing[:2])
   print(existing)
 
-..   * For changes since the previous release, see the :ref:`change-log`
+* :meth:`~.RandomGenerator.randint` supports broadcasting inputs.
 
 * Support for Lemire’s method of generating uniform integers on an
   arbitrary interval by setting ``use_masked=True`` in
@@ -122,3 +120,28 @@ And in more detail:
 
   %timeit rg.randint(0, 1535, use_masked=False)
   %timeit numpy.random.randint(0, 1535)
+
+* :meth:`~.RandomGenerator.multinomial`
+  supports multidimensional values of ``n``
+
+.. ipython:: python
+
+  rg.multinomial([10, 100], np.ones(6) / 6.)
+
+* :meth:`~.RandomGenerator.choice`
+  is much faster when sampling small amounts from large arrays
+
+.. ipython:: python
+
+  x = np.arange(1000000)
+  %timeit rg.choice(x, 10)
+
+* :meth:`~.RandomGenerator.choice`
+  supports the ``axis`` keyword to work with multidimensional arrays.
+
+.. ipython:: python
+
+  x = np.reshape(np.arange(20), (2, 10))
+  rg.choice(x, 2, axis=1)
+
+..   * For changes since the previous release, see the :ref:`change-log`
diff --git a/numpy/random/dsfmt.pyx b/numpy/random/dsfmt.pyx
@@ -76,31 +76,46 @@ cdef class DSFMT:
     Parameters
     ----------
     seed : {None, int, array_like}, optional
-        Random seed initializing the pseudo-random number generator.
-        Can be an integer in [0, 2**32-1], array of integers in
-        [0, 2**32-1] or ``None`` (the default). If `seed` is ``None``,
-        then ``DSFMT`` will try to read entropy from ``/dev/urandom``
-        (or the Windows analog) if available to produce a 32-bit
-        seed. If unavailable, a 32-bit hash of the time and process
-        ID is used.
+        Random seed used to initialize the pseudo-random number generator.  Can
+        be any integer between 0 and 2**32 - 1 inclusive, an array (or other
+        sequence) of unsigned 32-bit integers, or ``None`` (the default).  If
+        `seed` is ``None``, a 32-bit unsigned integer is read from
+        ``/dev/urandom`` (or the Windows analog) if available. If unavailable,
+        a 32-bit hash of the time and process ID is used.
 
     Notes
     -----
-    ``DSFMT`` directly provides generators for doubles, and unsigned 32 and 64-
-    bit integers [1]_ . These are not directly available and must be consumed
-    via a ``RandomGenerator`` object.
+    ``DSFMT`` provides a capsule containing function pointers that produce
+    doubles, and unsigned 32 and 64- bit integers [1]_ . These are not
+    directly consumable in Python and must be consumed by a ``RandomGenerator``
+    or similar object that supports low-level access.
 
     The Python stdlib module "random" also contains a Mersenne Twister
     pseudo-random number generator.
 
+    **State and Seeding**
+
+    The ``DSFMT`` state vector consists of a 384 element array of 64-bit
+    unsigned integers plus a single integer value between 0 and 382
+    indicating the current position within the main array. The implementation
+    used here augments this with a 382 element array of doubles which are used
+    to efficiently access the random numbers produced by the dSFMT generator.
+
+    ``DSFMT`` 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.
+
     **Parallel Features**
 
     ``DSFMT`` can be used in parallel applications by calling the method
     ``jump`` which advances the state as-if :math:`2^{128}` random numbers
     have been generated [2]_. This allows the original sequence to be split
-    so that distinct segments can be used in each worker process.  All
-    generators should be initialized with the same seed to ensure that the
-    segments come from the same sequence.
+    so that distinct segments can be used in each worker process. All
+    generators should be initialized with the same seed to ensure that
+    the segments come from the same sequence.
 
     >>> from numpy.random.entropy import random_entropy
     >>> from numpy.random import RandomGenerator, DSFMT
@@ -110,25 +125,10 @@ cdef class DSFMT:
     >>> for i in range(10):
     ...     rs[i].brng.jump()
 
-    **State and Seeding**
-
-    The ``DSFMT`` state vector consists of a 384 element array of
-    64-bit unsigned integers plus a single integer value between 0 and 382
-    indicating  the current position within the main array. The implementation
-    used here augments this with a 382 element array of doubles which are used
-    to efficiently access the random numbers produced by the dSFMT generator.
-
-    ``DSFMT`` 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.
-
     **Compatibility Guarantee**
 
-    ``DSFMT`` does makes a guarantee that a fixed seed and will always
-    produce the same results.
+    ``DSFMT`` makes a guarantee that a fixed seed and will always produce
+    the same random integer stream.
 
     References
     ----------

diff --git a/numpy/random/entropy.pyx b/numpy/random/entropy.pyx
@@ -24,18 +24,18 @@ cdef Py_ssize_t compute_numel(size):
 
 def seed_by_array(object seed, Py_ssize_t n):
     """
-    Transforms a seed array into an initial state
+    Transforms a seed array into an initial state using SplitMix64
 
     Parameters
     ----------
-    seed: array, 1d, uint64
-        Array to use.  If seed is a scalar, promote to array.
+    seed: int, array or uint64
+        Array to use.  If seed is a scalar, it is promoted to an array.
     n : int
-        Number of 64-bit unsigned integers required
+        Number of 64-bit unsigned integers required in the seed
 
     Notes
     -----
-    Uses splitmix64 to perform the transformation
+    Uses SplitMix64 to transform the input to a seed
     """
     cdef uint64_t seed_copy = 0
     cdef uint64_t[::1] seed_array
@@ -106,8 +106,9 @@ def random_entropy(size=None, source='system'):
 
     Returns
     -------
-    entropy : scalar or ndarray
-        Entropy bits in 32-bit unsigned integers
+    entropy : scalar or array
+        Entropy bits in 32-bit unsigned integers. A scalar is returned if size
+        is `None`.
 
     Notes
     -----

diff --git a/numpy/random/generator.pyx b/numpy/random/generator.pyx
@@ -26,8 +26,8 @@ cdef class RandomGenerator:
 
     Container for the Basic Random Number Generators.
 
-    ``RandomGenerator`` exposes a number of methods for generating random
-    numbers drawn from a variety of probability distributions. In addition to the
+    ``RandomGenerator`` exposes methods for generating random numbers drawn
+    from a variety of probability distributions. In addition to the
     distribution-specific arguments, each method takes a keyword argument
     `size` that defaults to ``None``. If `size` is ``None``, then a single
     value is generated and returned. If `size` is an integer, then a 1-D
@@ -37,9 +37,9 @@ cdef class RandomGenerator:
     **No Compatibility Guarantee**
 
     ``RandomGenerator`` is evolving and so it isn't possible to provide a
-    compatibility guarantee like NumPy does. In particular, better algorithms
-    have already been added. This will change once ``RandomGenerator``
-    stabilizes.
+    compatibility guarantee like ``RandomState``. In particular, better
+    algorithms have already been added and bugs that change the stream
+    have been fixed. This will change once ``RandomGenerator`` stabilizes.
 
     Parameters
     ----------
@@ -51,10 +51,10 @@ cdef class RandomGenerator:
     -----
     The Python stdlib module `random` contains pseudo-random number generator
     with a number of methods that are similar to the ones available in
-    ``RandomGenerator``. It uses Mersenne Twister, and this basic RNG can be
-    accessed using ``MT19937``. ``RandomGenerator``, besides being
+    ``RandomGenerator``. It uses Mersenne Twister, which is available  by
+    using the ``MT19937`` basic RNG. ``RandomGenerator``, besides being
     NumPy-aware, has the advantage that it provides a much larger number
-    of probability distributions to choose from.
+    of probability distributions from which to choose.
 
     Examples
     --------

diff --git a/numpy/random/mt19937.pyx b/numpy/random/mt19937.pyx
@@ -55,24 +55,26 @@ cdef class MT19937:
     seed : {None, int, array_like}, optional
         Random seed used to initialize the pseudo-random number generator.  Can
         be any integer between 0 and 2**32 - 1 inclusive, an array (or other
-        sequence) of such integers, or ``None`` (the default).  If `seed` is
-        ``None``, then will attempt to read data from ``/dev/urandom``
-        (or the Windows analog) if available or seed from the clock otherwise.
+        sequence) of unsigned 32-bit integers, or ``None`` (the default).  If
+        `seed` is ``None``, a 32-bit unsigned integer is read from
+        ``/dev/urandom`` (or the Windows analog) if available. If unavailable,
+        a 32-bit hash of the time and process ID is used.
 
     Notes
     -----
-    ``MT19937`` directly provides generators for doubles, and unsigned 32 and 64-
-    bit integers [1]_ . These are not directly available and must be consumed
-    via a ``RandomGenerator`` object.
+    ``MT19937`` provides a capsule containing function pointers that produce
+    doubles, and unsigned 32 and 64- bit integers [1]_. These are not
+    directly consumable in Python and must be consumed by a ``RandomGenerator``
+    or similar object that supports low-level access.
 
     The Python stdlib module "random" also contains a Mersenne Twister
     pseudo-random number generator.
 
     **State and Seeding**
 
-    The ``MT19937`` state vector consists of a 768 element array of
+    The ``MT19937`` state vector consists of a 768-element array of
     32-bit unsigned integers plus a single integer value between 0 and 768
-    indicating  the current position within the main array.
+    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
@@ -81,22 +83,14 @@ cdef class MT19937:
     for the seed can only initialize a small range of the possible initial
     state values.
 
-    **Compatibility Guarantee**
-
-    ``MT19937`` make a compatibility guarantee. A fixed seed and a fixed
-    series of calls to ``MT19937`` methods will always produce the same
-    results up to roundoff error except when the values were incorrect.
-    Incorrect values will be fixed and the version in which the fix was
-    made will be noted in the relevant docstring.
-
     **Parallel Features**
 
     ``MT19937`` can be used in parallel applications by
     calling the method ``jump`` which advances the state as-if :math:`2^{128}`
-    random numbers have been generated ([1]_, [2]_). This allows the original sequence to
-    be split so that distinct segments can be used in each worker process.  All
-    generators should be initialized with the same seed to ensure that the
-    segments come from the same sequence.
+    random numbers have been generated ([1]_, [2]_). This allows the original
+    sequence to be split so that distinct segments can be used in each worker
+    process. All generators should be initialized with the same seed to ensure
+    that the segments come from the same sequence.
 
     >>> from numpy.random.entropy import random_entropy
     >>> from numpy.random import RandomGenerator, MT19937
@@ -106,6 +100,11 @@ cdef class MT19937:
     >>> for i in range(10):
     ...     rs[i].brng.jump(i)
 
+    **Compatibility Guarantee**
+
+    ``MT19937`` makes a guarantee that a fixed seed and will always produce
+    the same random integer stream.
+
     References
     ----------
     .. [1] Hiroshi Haramoto, Makoto Matsumoto, and Pierre L\'Ecuyer, "A Fast

diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx
@@ -34,14 +34,15 @@ cdef class RandomState:
     array filled with generated values is returned. If `size` is a tuple,
     then an array with that shape is filled and returned.
 
-    *Compatibility Guarantee*
-    A fixed seed and a fixed series of calls to 'RandomState' methods using
-    the same parameters will always produce the same results up to roundoff
-    error except when the values were incorrect. Incorrect values will be
-    fixed and the NumPy version in which the fix was made will be noted in
-    the relevant docstring. Extension of existing parameter ranges and the
-    addition of new parameters is allowed as long the previous behavior
-    remains unchanged.
+    **Compatibility Guarantee**
+
+    A fixed basic RNG using a fixed seed and a fixed series of calls to
+    'RandomState' methods using the same parameters will always produce the
+    same results up to roundoff error except when the values were incorrect.
+    `RandomState` is effectively frozen and will only recieve updates that
+    are required by changes in the the internals of Numpy. More substantial
+    changes, including algorithmic improvements, are reserved for
+    `RandomGenerator`.
 
     Parameters
     ----------
@@ -63,6 +64,11 @@ cdef class RandomState:
     NumPy-aware, has the advantage that it provides a much larger number
     of probability distributions to choose from.
 
+    See Also
+    --------
+    randomgen.generator.RandomGenerator
+    randomgen.mt19937.MT19937
+
     """
     cdef public object _basicrng
     cdef brng_t *_brng