Merge pull request numpy#26385 from bmwoodruff/links-random-folder

DOC: Updated remaining links in random folder

Author: charris

doc/source/reference/c-api/coremath.rst

@@ -1,7 +1,7 @@
 NumPy core math library
 =======================
 
-The numpy core math library ('npymath') is a first step in this direction. This
+The numpy core math library (``npymath``) is a first step in this direction. This
 library contains most math-related C99 functionality, which can be used on
 platforms where C99 is not well supported. The core math functions have the
 same API as the C99 ones, except for the ``npy_*`` prefix.
@@ -304,7 +304,7 @@ Linking against the core math library in an extension
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To use the core math library that NumPy ships as a static library in your own
-Python extension, you need to add the npymath compile and link options to your
+Python extension, you need to add the ``npymath`` compile and link options to your
 extension. The exact steps to take will depend on the build system you are using.
 The generic steps to take are:
 

doc/source/reference/distutils.rst

@@ -14,7 +14,7 @@ Packaging (:mod:`numpy.distutils`)
 .. warning::
 
    Note that ``setuptools`` does major releases often and those may contain
-   changes that break ``numpy.distutils``, which will *not* be updated anymore
+   changes that break :mod:`numpy.distutils`, which will *not* be updated anymore
    for new ``setuptools`` versions. It is therefore recommended to set an
    upper version bound in your build configuration for the last known version
    of ``setuptools`` that works with your build.

doc/source/reference/random/compatibility.rst

@@ -22,7 +22,7 @@ outside of NumPy's control that limit our ability to guarantee much more than
 this. For example, different CPUs implement floating point arithmetic
 differently, and this can cause differences in certain edge cases that cascade
 to the rest of the stream. `Generator.multivariate_normal`, for another
-example, uses a matrix decomposition from ``numpy.linalg``. Even on the same
+example, uses a matrix decomposition from `numpy.linalg`. Even on the same
 platform, a different build of ``numpy`` may use a different version of this
 matrix decomposition algorithm from the LAPACK that it links to, causing
 `Generator.multivariate_normal` to return completely different (but equally

doc/source/reference/random/extending.rst

@@ -4,15 +4,15 @@
 
 Extending
 =========
-The BitGenerators have been designed to be extendable using standard tools for
-high-performance Python -- numba and Cython.  The `~Generator` object can also
-be used with user-provided BitGenerators as long as these export a small set of
-required functions.
+The `BitGenerator`\ s have been designed to be extendable using standard tools
+for high-performance Python -- numba and Cython.  The `Generator` object can
+also be used with user-provided `BitGenerator`\ s as long as these export a
+small set of required functions.
 
 Numba
 -----
 Numba can be used with either CTypes or CFFI.  The current iteration of the
-BitGenerators all export a small set of functions through both interfaces.
+`BitGenerator`\ s all export a small set of functions through both interfaces.
 
 This example shows how numba can be used to produce gaussian samples using
 a pure Python implementation which is then compiled.  The random numbers are
@@ -32,7 +32,7 @@ the `Examples`_ section below.
 Cython
 ------
 
-Cython can be used to unpack the ``PyCapsule`` provided by a BitGenerator.
+Cython can be used to unpack the ``PyCapsule`` provided by a `BitGenerator`.
 This example uses `PCG64` and the example from above.  The usual caveats
 for writing high-performance code using Cython -- removing bounds checks and
 wrap around, providing array alignment information -- still apply.
@@ -41,7 +41,7 @@ wrap around, providing array alignment information -- still apply.
     :language: cython
     :end-before: example 2
 
-The BitGenerator can also be directly accessed using the members of the ``bitgen_t``
+The `BitGenerator` can also be directly accessed using the members of the ``bitgen_t``
 struct.
 
 .. literalinclude:: ../../../../numpy/random/_examples/cython/extending_distributions.pyx
@@ -81,9 +81,9 @@ directly from the ``_generator`` shared object, using the `BitGenerator.cffi` in
 
 New BitGenerators
 -----------------
-`~Generator` can be used with user-provided `~BitGenerator`\ s. The simplest
-way to write a new BitGenerator is to examine the pyx file of one of the
-existing BitGenerators. The key structure that must be provided is the
+`Generator` can be used with user-provided `BitGenerator`\ s. The simplest
+way to write a new `BitGenerator` is to examine the pyx file of one of the
+existing `BitGenerator`\ s. The key structure that must be provided is the
 ``capsule`` which contains a ``PyCapsule`` to a struct pointer of type
 ``bitgen_t``,
 
@@ -98,11 +98,11 @@ existing BitGenerators. The key structure that must be provided is the
   } bitgen_t;
 
 which provides 5 pointers. The first is an opaque pointer to the data structure
-used by the BitGenerators.  The next three are function pointers which return
-the next 64- and 32-bit unsigned integers, the next random double and the next
-raw value.  This final function is used for testing and so can be set to
-the next 64-bit unsigned integer function if not needed. Functions inside
-``Generator`` use this structure as in
+used by the `BitGenerator`\ s.  The next three are function pointers which
+return the next 64- and 32-bit unsigned integers, the next random double and
+the next raw value. This final function is used for testing and so can be set
+to the next 64-bit unsigned integer function if not needed. Functions inside
+`Generator` use this structure as in
 
 .. code-block:: c
 

doc/source/reference/random/multithreading.rst

@@ -104,8 +104,8 @@ that does not use an existing array due to array creation overhead.
 
     Out[6]: 125 ms ± 309 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
 
-Note that if `threads` is not set by the user, it will be determined by
-`multiprocessing.cpu_count()`.
+Note that if ``threads`` is not set by the user, it will be determined by
+``multiprocessing.cpu_count()``.
 
 .. code-block:: ipython
 

doc/source/reference/random/new-or-different.rst

@@ -9,38 +9,40 @@ 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
------------------- -------------------- -------------
-`~.Generator`      `~.RandomState`      ``Generator`` requires a stream
-                                        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.
------------------- -------------------- -------------
-``random``         ``random_sample``,   Access the values in a BitGenerator,
-                   ``rand``             convert them to ``float64`` in the
-                                        interval ``[0.0.,`` `` 1.0)``.
-                                        In addition to the ``size`` kwarg, now
-                                        supports ``dtype='d'`` or ``dtype='f'``,
-                                        and an ``out`` kwarg to fill a user-
-                                        supplied array.
-
-                                        Many other distributions are also
-                                        supported.
------------------- -------------------- -------------
-``integers``       ``randint``,         Use the ``endpoint`` kwarg to adjust
-                   ``random_integers``  the inclusion or exclusion of the
-                                        ``high`` interval endpoint
-================== ==================== =============
+======================= ================== =============
+Feature                 Older Equivalent   Notes
+----------------------- ------------------ -------------
+`Generator`             `RandomState`      `Generator` requires a stream
+                                           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.
+----------------------- ------------------ -------------
+`~.Generator.random`    `random_sample`,   Access the values in a
+                        `rand`             BitGenerator, convert them to
+                                           ``float64`` in the interval
+                                           ``[0.0., 1.0)``. In addition
+                                           to the ``size`` kwarg, now
+                                           supports ``dtype='d'`` or
+                                           ``dtype='f'``, and an ``out``
+                                           kwarg to fill a user-supplied
+                                           array.
+
+                                           Many other distributions are also
+                                           supported.
+----------------------- ------------------ -------------
+`~.Generator.integers`  `randint`,         Use the ``endpoint`` kwarg to
+                        `random_integers`  adjust the inclusion or exclusion
+                                           of the ``high`` interval endpoint.
+======================= ================== =============
 
 * 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`. Because of the change in algorithms, it is not
-  possible to reproduce the exact random values using ``Generator`` for these
+  possible to reproduce the exact random values using `Generator` for these
   distributions or any distribution method that relies on them.
 
 .. ipython:: python
@@ -63,8 +65,8 @@ Feature            Older Equivalent     Notes
 
 * `~.Generator.integers` is now the canonical way to generate integer
   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
+  `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`,

doc/source/reference/random/parallel.rst

@@ -13,39 +13,39 @@ or distributed).
 ------------------------
 
 NumPy allows you to spawn new (with very high probability) independent
-`~BitGenerator` and `~Generator` instances via their ``spawn()`` method.
-This spawning is implemented by the `~SeedSequence` used for initializing
+`BitGenerator` and `Generator` instances via their ``spawn()`` method.
+This spawning is implemented by the `SeedSequence` used for initializing
 the bit generators random stream.
 
-`~SeedSequence` `implements an algorithm`_ to process a user-provided seed,
+`SeedSequence` `implements an algorithm`_ to process a user-provided seed,
 typically as an integer of some size, and to convert it into an initial state for
-a `~BitGenerator`. It uses hashing techniques to ensure that low-quality seeds
+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` has a state consisting of 624
-`uint32` integers. A naive way to take a 32-bit integer seed would be to just set
+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`, 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.
 
-`~SeedSequence` avoids these problems by using successions of integer hashes
+`SeedSequence` avoids these problems by using successions of integer hashes
 with good `avalanche properties`_ to ensure that flipping any bit in the input
 has about a 50% chance of flipping any bit in the output. Two input seeds that
 are very close to each other will produce initial states that are very far
 from each other (with very high probability). It is also constructed in such
 a way that you can provide arbitrary-sized integers or lists of integers.
-`~SeedSequence` will take all of the bits that you provide and mix them
-together to produce however many bits the consuming `~BitGenerator` needs to
+`SeedSequence` will take all of the bits that you provide and mix them
+together to produce however many bits the consuming `BitGenerator` needs to
 initialize itself.
 
 These properties together mean that we can safely mix together the usual
-user-provided seed with simple incrementing counters to get `~BitGenerator`
+user-provided seed with simple incrementing counters to get `BitGenerator`
 states that are (to very high probability) independent of each other. We can
 wrap this together into an API that is easy to use and difficult to misuse.
-Note that while `~SeedSequence` attempts to solve many of the issues related to
+Note that while `SeedSequence` attempts to solve many of the issues related to
 user-provided small seeds, we still :ref:`recommend<recommend-secrets-randbits>`
 using :py:func:`secrets.randbits` to generate seeds with 128 bits of entropy to
 avoid the remaining biases introduced by human-chosen seeds.
@@ -62,7 +62,7 @@ avoid the remaining biases introduced by human-chosen seeds.
 
 .. end_block
 
-For convenience the direct use of `~SeedSequence` is not necessary.
+For convenience the direct use of `SeedSequence` is not necessary.
 The above ``streams`` can be spawned directly from a parent generator
 via `~Generator.spawn`:
 
@@ -74,7 +74,7 @@ via `~Generator.spawn`:
 .. end_block
 
 Child objects can also spawn to make grandchildren, and so on.
-Each child has a `~SeedSequence` with its position in the tree of spawned
+Each child has a `SeedSequence` with its position in the tree of spawned
 child objects mixed in with the user-provided seed to generate independent
 (with very high probability) streams.
 
@@ -92,7 +92,7 @@ Python has increasingly-flexible mechanisms for parallelization available, and
 this scheme fits in very well with that kind of use.
 
 Using this scheme, an upper bound on the probability of a collision can be
-estimated if one knows the number of streams that you derive. `~SeedSequence`
+estimated if one knows the number of streams that you derive. `SeedSequence`
 hashes its inputs, both the seed and the spawn-tree-path, down to a 128-bit
 pool by default. The probability that there is a collision in
 that pool, pessimistically-estimated ([1]_), will be about :math:`n^2*2^{-128}` where
@@ -110,7 +110,7 @@ territory ([2]_).
 .. [2] In this calculation, we can mostly ignore the amount of numbers drawn from each
        stream. See :ref:`upgrading-pcg64` for the technical details about
        `PCG64`. The other PRNGs we provide have some extra protection built in
-       that avoids overlaps if the `~SeedSequence` pools differ in the
+       that avoids overlaps if the `SeedSequence` pools differ in the
        slightest bit. `PCG64DXSM` 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
@@ -133,7 +133,7 @@ territory ([2]_).
 Sequence of integer seeds
 -------------------------
 
-As discussed in the previous section, `~SeedSequence` can not only take an
+As discussed in the previous section, `SeedSequence` can not only take an
 integer seed, it can also take an arbitrary-length sequence of (non-negative)
 integers. If one exercises a little care, one can use this feature to design
 *ad hoc* schemes for getting safe parallel PRNG streams with similar safety
@@ -164,7 +164,7 @@ integer in a list.
 This can be used to replace a number of unsafe strategies that have been used
 in the past which try to combine the root seed and the ID back into a single
 integer seed value. For example, it is common to see users add the worker ID to
-the root seed, especially with the legacy `~RandomState` code.
+the root seed, especially with the legacy `RandomState` code.
 
 .. code-block:: python
 
@@ -253,13 +253,13 @@ are listed below.
 +-----------------+-------------------------+-------------------------+-------------------------+
 | BitGenerator    | Period                  |  Jump Size              | Bits per Draw           |
 +=================+=========================+=========================+=========================+
-| MT19937         | :math:`2^{19937}-1`     | :math:`2^{128}`         | 32                      |
+| `MT19937`       | :math:`2^{19937}-1`     | :math:`2^{128}`         | 32                      |
 +-----------------+-------------------------+-------------------------+-------------------------+
-| PCG64           | :math:`2^{128}`         | :math:`~2^{127}` ([3]_) | 64                      |
+| `PCG64`         | :math:`2^{128}`         | :math:`~2^{127}` ([3]_) | 64                      |
 +-----------------+-------------------------+-------------------------+-------------------------+
-| PCG64DXSM       | :math:`2^{128}`         | :math:`~2^{127}` ([3]_) | 64                      |
+| `PCG64DXSM`     | :math:`2^{128}`         | :math:`~2^{127}` ([3]_) | 64                      |
 +-----------------+-------------------------+-------------------------+-------------------------+
-| Philox          | :math:`2^{256}`         | :math:`2^{128}`         | 64                      |
+| `Philox`        | :math:`2^{256}`         | :math:`2^{128}`         | 64                      |
 +-----------------+-------------------------+-------------------------+-------------------------+
 
 .. [3] The jump size is :math:`(\phi-1)*2^{128}` where :math:`\phi` is the

doc/source/reference/random/performance.rst

@@ -24,7 +24,7 @@ even on 32-bit processes, this is your choice.
 
 `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
+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
 many systems.
 

doc/source/reference/random/upgrading-pcg64.rst

@@ -2,7 +2,7 @@
 
 .. currentmodule:: numpy.random
 
-Upgrading ``PCG64`` with ``PCG64DXSM``
+Upgrading `PCG64` with `PCG64DXSM`
 ======================================
 
 Uses of the `PCG64` `BitGenerator` in a massively-parallel context have been

numpy/random/_mt19937.pyx

@@ -67,17 +67,17 @@ cdef class MT19937(BitGenerator):
 
     Notes
     -----
-    ``MT19937`` provides a capsule containing function pointers that produce
+    `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 ``Generator``
+    directly consumable in Python and must be consumed by a `Generator`
     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 624-element array of
+    The `MT19937` state vector consists of a 624-element array of
     32-bit unsigned integers plus a single integer value between 0 and 624
     that indexes the current position within the main array.
 
@@ -111,7 +111,7 @@ cdef class MT19937(BitGenerator):
 
     **Compatibility Guarantee**
 
-    ``MT19937`` makes a guarantee that a fixed seed will always produce
+    `MT19937` makes a guarantee that a fixed seed will always produce
     the same random integer stream.
 
     References