DOC: rework randomgen docs to integrate with numpy and fix some links

mattip · bashtage · Mar 27, 2018 · Mar 27, 2018 · Mar 27, 2018 · Mar 28, 2018
commit a8027f727ef3a60ca82934d00faafe2651afb0b3
diff --git a/doc/source/reference/randomgen/extending.rst b/doc/source/reference/randomgen/extending.rst
@@ -59,6 +59,8 @@ directly in Numba after compiling the file distributions.c into a DLL or so.
 An example showing the use of a more complicated distribution is in the
 examples folder.

+.. _randomgen_cython:
+
 Cython
 ======
 

diff --git a/doc/source/reference/randomgen/generator.rst b/doc/source/reference/randomgen/generator.rst
@@ -1,18 +1,16 @@
+.. currentmodule:: numpy.random.randomgen
+
 Random Generator
 ----------------
-The :class:`~randomgen.generator.RandomGenerator` provides access to 
-a wide range of distributions, and served as a replacement for 
-:class:`~numpy.random.RandomState`.  The main difference between 
-the two is that :class:`~randomgen.generator.RandomGenerator` relies
-on an additional basic RNG to manage state and generate the random 
-bits which are then transformed into random values from useful 
-distributions. The default basic RNG used by 
-:class:`~randomgen.generator.RandomGenerator` is 
-:class:`~randomgen.xoroshiro128.Xoroshiro128`.  The basic RNG can be 
-changed by passing an instantized basic RNG to 
-:class:`~randomgen.generator.RandomGenerator`. 
+The :class:`~RandomGenerator` provides access to
+a wide range of distributions, and served as a replacement for
+:class:`~numpy.random.RandomState`.  The main difference between
+the two is that ``RandomGenerator`` relies on an additional basic RNG to
+manage state and generate the random bits, which are then transformed into
+random values from useful distributions. The default basic RNG used by
+``RandomGenerator`` is :class:`~xoroshiro128.Xoroshiro128`.  The basic RNG can be
+changed by passing an instantized basic RNG to ``RandomGenerator``.
 
-.. currentmodule:: numpy.random.randomgen.generator
 
 .. autoclass:: RandomGenerator
 	:exclude-members:

diff --git a/doc/source/reference/randomgen/index.rst b/doc/source/reference/randomgen/index.rst
@@ -1,30 +1,33 @@
-Randomgen.RandomGen
-===================
-This package contains replacements for the NumPy
-:class:`~numpy.random.RandomState` object that allows the core random number
-generator be be changed.
-
 .. current_module numpy.random.randomgen
 
+numpy.random.randomgen
+======================
+
+This package modernizes the legacy
+`~numpy.random.RandomState` object and allows changing the core random
+number generator (RNG). The `~numpy.random.randomgen.RandomGenerator` can
+be initialized with a number of different RNGs, and exposes many different
+probability distributions.
+
+
 Quick Start
 -----------
 
-Like :mod:`numpy.random`, RandomGen can be used at the module level. 
-This uses the default :class:`~randomgen.generator.RandomGenerator` which 
-uses normals provided by :class:`~randomgen.xoroshiro128.Xoroshiro128`.
+By default, `generator.RandomGenerator` uses normals provided by
+`xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in
+`numpy.random`
 
 .. code-block:: python
 
   # As replacement for numpy.random
   import randomgen.generator as random
   random.standard_normal()
 
-:class:`~randomgen.generator.RandomGenerator` can also be used as a 
-replacement for :class:`~numpy.random.RandomState`, although the random
-values are generated by :class:`~randomgen.xoroshiro128.Xoroshiro128`. It 
-also isn't possible to directly seed a 
-:class:`~randomgen.generator.RandomGenerator`.
-
+`numpy.random.randomgen.RandomGenerator` can also be used as a replacement for
+`~numpy.random.RandomState`, although the random values are generated by
+`~numpyrandom.randomgen.xoroshiro128.Xoroshiro128`. Since ``randomgen``
+separates the `~numpy.random.randomgen.RandomGenerator` from the RNG, it is not
+possible to directly seed the generator.
 
 .. code-block:: python
 
@@ -34,9 +37,9 @@ also isn't possible to directly seed a
   rg.standard_normal()
 
 
-Seeds can be passed to any of the basic RNGs. Here :class:`~randomgen.mt19937.MT19937`
-is used and the :class:`~randomgen.generator.RandomGenerator` is accessed via 
-the property :attr:`~randomgen.mt19937.MT19937.generator`.
+Seeds can be passed to any of the basic RNGs. Here `numpy.random.randomgen.
+mt19937.MT19937` is used and the `~numpy.random.randomgen.RandomGenerator` is
+accessed via the attribute `~numpy.random.randomgen.mt19937.MT19937.generator`.
 
 .. code-block:: python
 
@@ -48,24 +51,23 @@ the property :attr:`~randomgen.mt19937.MT19937.generator`.
 Introduction
 ------------
 RandomGen takes a different approach to producing random numbers from the
-:class:`numpy.random.RandomState` object used in NumPy.  Random number
-generation is separated into two components, a basic RNG and a random
-generator.
+:class:`numpy.random.RandomState` object.  Random number generation is
+separated into two components, a basic RNG and a random generator.
 
-The basic RNG has a limited set of responsibilities -- it manages the
+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.
 
-The random generator (:class:`~randomgen.generator.RandomGenerator`) takes the
+The `random generator <~numpy.random.randomgen.RandomGenerator>` takes the
 basic RNG-provided functions and transforms them into more useful
 distributions, e.g., simulated normal random values. This structure allows
 alternative basic RNGs to be used without code duplication.
 
-The :class:`~randomgen.generator.RandomGenerator` is the user-facing object
+The `~numpy.random.randomgen.RandomGenerator` is the user-facing object
 that is nearly identical to :class:`~numpy.random.RandomState`. The canonical
-method to initialize a generator passes a basic RNG --
-:class:`~randomgen.mt19937.MT19937`, the underlying RNG in NumPy  -- as the
+method to initialize a generator passes a basic RNG -- `~numpy.random.
+randomgen.mt19937.MT19937`, the underlying RNG in NumPy  -- as the
 sole argument. Note that the basic RNG must be instantized.
 
 .. code-block:: python
@@ -81,9 +83,9 @@ Seed information is directly passed to the basic RNG.
   rg = RandomGenerator(MT19937(12345))
   rg.random_sample()
 
-A shorthand method is also available which uses the
-:meth:`~randomgen.mt19937.MT19937.generator` property from a basic RNG to
-access an embedded random generator.
+A shorthand method is also available which uses the `~numpy.random.randomgen.
+mt19937.MT19937.generator` property from a basic RNG to access an embedded
+random generator.
 
 .. code-block:: python
 
@@ -95,13 +97,14 @@ What's New or Different
 .. warning::
 
   The Box-Muller method used to produce NumPy's normals is no longer available
-  in :class:`~randomgen.generator.RandomGenerator`.  It is not possible to 
-  reproduce the random values using :class:`~randomgen.generator.RandomGenerator` 
-  for the normal distribution or any other distribution that relies on the
-  normal such as the gamma or student's t. If you require backward compatibility, a 
-  legacy generator, :class:`~randomgen.legacy.LegacyGenerator`, has been created
-  which can fully reproduce the sequence produced by NumPy.
-
+  in `~numpy.random.randomgen.RandomGenerator`.  It is not possible to
+  reproduce the random values using `~numpy.random.randomgen.RandomGenerator`
+  for the normal distribution or any other distribution that
+  relies on the normal such as the gamma or student's t. If you require
+  backward compatibility, a legacy generator, `~numpy.random.randomgen.legacy.
+  LegacyGenerator`, has been created which can fully reproduce the sequence
+  produced by NumPy.
+
 * The normal, exponential and gamma generators use 256-step Ziggurat
   methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
   implementations.
@@ -110,20 +113,18 @@ What's New or Different
   select distributions
 * Optional ``out`` argument that allows existing arrays to be filled for
   select distributions
-* Simulate from the complex normal distribution
-  (:meth:`~randomgen.generator.RandomGenerator.complex_normal`)
-* :func:`~randomgen.entropy.random_entropy` provides access to the system
+* `~numpy.random.randomgen.entropy.random_entropy` provides access to the system
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
-* All basic random generators functions to produce doubles, uint64s and
-  uint32s via CTypes (:meth:`~randomgen.xoroshiro128.Xoroshiro128.ctypes`)
-  and CFFI (:meth:`~randomgen.xoroshiro128.Xoroshiro128.cffi`).  This allows
-  these basic RNGs to be used in numba.
+* All basic random generators functions can produce doubles, uint64s and
+  uint32s via CTypes (`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.ctypes`)
+  and CFFI (:meth:`~numpy.random.randomgen.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.
+  :ref:`Cython <randomgen_cython>`.
 * Support for Lemire’s method [Lemire]_ of generating uniform integers on an
   arbitrary interval by setting ``use_masked=True`` in
-  (:meth:`~randomgen.generator.RandomGenerator.randint`).
+  `~umpy.random.randomgen.generator.RandomGenerator.randint`.
 
 
 See :ref:`new-or-different` for a complete list of improvements and
@@ -144,41 +145,40 @@ The main innovation is the inclusion of a number of alternative pseudo-random nu
 generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are:
 
 * MT19937 - The standard NumPy generator.  Produces identical results to NumPy
-  using the same seed/state. Adds a jump function that advances the generator
-  as-if 2**128 draws have been made (:meth:`~randomgen.mt19937.MT19937.jump`).
-  See `NumPy's documentation`_.
+  using the same seed/state. Adds a
+  `~numpy.random.randomgen.mt19937.MT19937.jump` function that advances the
+  generator as-if ``2**128`` draws have been made.  See `numpy.random`.
 * dSFMT - SSE2 enabled versions of the MT19937 generator.  Theoretically
   the same, but with
E377
 a different state and so it is not possible to produce a
   sequence identical to MT19937. Supports ``jump`` and so can
   be used in parallel applications. See the `dSFMT authors' page`_.
 * XoroShiro128+ - Improved version of XorShift128+ with better performance
   and statistical quality. Like the XorShift generators, it can be jumped
   to produce multiple streams in parallel applications. See
-  :meth:`~randomgen.xoroshiro128.Xoroshiro128.jump` for details.
+  `~numpy.random.randomgen.xoroshiro128.Xoroshiro128.jump` for details.
   More information about this PRNG is available at the
   `xorshift, xoroshiro and xoshiro authors' page`_.
 * XorShift1024*φ - Fast fast generator based on the XSadd
   generator. Supports ``jump`` and so can be used in
   parallel applications. See the documentation for
-  :meth:`~randomgen.xorshift1024.Xorshift1024.jump` for details. More information
-  about these PRNGs is available at the
+  `~numpy.random.randomgen.xorshift1024.Xorshift1024.jump` for details. More
+  information about these PRNGs 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
-  :meth:`~randomgen.xoshiro256starstar.Xoshirt256StarStar.jump` for details. More
-  information about these PRNGs is available at the
+  `~numpy.random.randomgen.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
-  :meth:`~randomgen.pcg64.PCG64.advance`. PCG-64 has a period of
+  `~numpy.random.randomgen.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.
 * 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.
 
-.. _`NumPy's documentation`: https://docs.scipy.org/doc/numpy/reference/routines.random.html
 .. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/
 .. _`xorshift, xoroshiro and xoshiro authors' page`:  http://xoroshiro.di.unimi.it/
 .. _`PCG author's page`: http://www.pcg-random.org/
@@ -215,14 +215,12 @@ New Features
 
 Changes
 ~~~~~~~
+
+This package was developed independently of NumPy and was integrated in version
+1.17.0. The original repo is at https://github.com/bashtage/randomgen.
+
 .. toctree::
    :maxdepth: 2
 
    Change Log <change-log>
 
-Indices and tables
-~~~~~~~~~~~~~~~~~~
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/numpy/random/randomgen/generator.pyx b/numpy/random/randomgen/generator.pyx
@@ -49,7 +49,7 @@ cdef class RandomGenerator:
 
     Notes
     -----
-    The Python stdlib module "random" contains pseudo-random number generator
+    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
-Original file line number
+Diff line change
@@ Expand Up @@
     An example showing the use of a more complicated distribution is in the
     examples folder.
+    .. _randomgen_cython:
     Cython
     ======
@@ Expand Down @@