DOC: fixup docs for current set of BitGenerators

numpy · charris · Jun 26, 2019 · Jun 26, 2019 · Jun 26, 2019 · Jun 26, 2019
commit 5c5965c1ee5ab64c84a928aba6e728a54280d5d6
diff --git a/doc/source/reference/random/bit_generators/index.rst b/doc/source/reference/random/bit_generators/index.rst
@@ -12,6 +12,27 @@ setting the state, jumping or advancing the state, and for accessing
 low-level wrappers for consumption by code that can efficiently
 access the functions provided, e.g., `numba <https://numba.pydata.org>`_.
 
+Supported BitGenerators
+=======================
+
+The included BitGenerators are:
+
+* MT19937 - The standard Python BitGenerator. Adds a `~mt19937.MT19937.jumped`
+  function that returns a new generator with state as-if ``2**128`` draws have
+  been made.
+* PCG-64 - Fast generator that support many parallel streams and
+  can be advanced by an arbitrary amount. See the documentation 
8000
for
+  :meth:`~.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.
+* Philox - a counter-based generator capable of being advanced an
+  arbitrary number of steps or generating independent streams. See the
+  `Random123`_ page for more details about this class of bit generators.
+
+.. _`PCG author's page`: http://www.pcg-random.org/
+.. _`Random123`: https://www.deshawresearch.com/resources_random123.html
+
+
 .. toctree::
    :maxdepth: 1
 
@@ -32,8 +53,8 @@ generate BitGenerators that are correlated or overlap within a few samples.
 
 NumPy uses a `SeedSequence` class to mix the seed in a reproducible way that
 introduces the necessary entropy to produce independent and largely non-
-overlapping streams. Small seeds may still be unable to reach all possible
-initialization states, which can cause biases among an ensemble of small-seed
+overlapping streams. Small seeds are unable to fill the complete range of
+initializaiton states, and lead to biases among an ensemble of small-seed
 runs. For many cases, that doesn't matter. If you just want to hold things in
 place while you debug something, biases aren't a concern.  For actual
 simulations whose results you care about, let ``SeedSequence(None)`` do its

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
@@ -159,28 +159,6 @@ one of two ways:
 * :ref:`independent-streams`
 * :ref:`jump-and-advance`
 
-Supported BitGenerators
------------------------
-The included BitGenerators are:
-
-* MT19937 - The standard Python BitGenerator. Adds a `~mt19937.MT19937.jumped`
-  function that returns a new generator with state as-if ``2**128`` draws have
-  been made.
-* PCG-64 - Fast generator that support many parallel streams and
-  can be advanced by an arbitrary amount. See the documentation for
-  :meth:`~.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.
-* Xorshiro256** and Xorshiro512** - The most recently introduced XOR,
-  shift, and rotate generator. Supports ``jumped`` and so can be used in
-  parallel applications. See the documentation for
-* 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 bit generators.
-
-.. _`PCG author's page`: http://www.pcg-random.org/
-.. _`Random123`: https://www.deshawresearch.com/resources_random123.html
-
 Concepts
 --------
 .. toctree::

diff --git a/doc/source/reference/random/performance.rst b/doc/source/reference/random/performance.rst
@@ -29,38 +29,38 @@ The column labeled MT19973 is used the same 32-bit generator as
 :class:`~generator.Generator`.
 
 .. csv-table::
-    :header: ,Xoshiro256**,Xoshiro512**,DSFMT,PCG64,MT19937,Philox,RandomState,ThreeFry
-    :widths: 14,14,14,14,14,14,14,14,14
+    :header: ,PCG64,MT19937,Philox,RandomState
+    :widths: 14,14,14,14,14
 
-    32-bit Unsigned Ints,2.6,2.9,3.5,3.2,3.3,4.8,3.2,7.6
-    64-bit Unsigned Ints,3.3,4.3,5.7,4.8,5.7,6.9,5.7,12.8
-    Uniforms,3.4,4.0,3.2,5.0,7.3,8.0,7.3,12.8
-    Normals,7.9,9.0,11.8,11.3,13.0,13.7,34.4,18.1
-    Exponentials,4.7,5.2,7.4,6.7,7.9,8.6,40.3,14.7
-    Gammas,29.1,27.5,28.5,30.6,34.2,35.1,58.1,47.6
-    Binomials,22.7,23.1,21.1,25.7,27.7,28.4,25.9,32.1
-    Laplaces,38.5,38.1,36.9,41.1,44.5,45.4,46.9,50.2
-    Poissons,46.9,50.9,46.4,58.1,68.4,70.2,86.0,88.2
+    32-bit Unsigned Ints,3.2,3.3,4.8,3.2
+    64-bit Unsigned Ints,4.8,5.7,6.9,5.7
+    Uniforms,5.0,7.3,8.0,7.3
+    Normals,11.3,13.0,13.7,34.4
+    Exponentials,6.7,7.9,8.6,40.3
+    Gammas,30.6,34.2,35.1,58.1
+    Binomials,25.7,27.7,28.4,25.9
+    Laplaces,41.1,44.5,45.4,46.9
+    Poissons,58.1,68.4,70.2,86.0
 
 
 The next table presents the performance in percentage relative to values
 generated by the legagy generator, `RandomState(MT19937())`. The overall
 performance was computed using a geometric mean.
 
 .. csv-table::
-    :header: ,Xoshiro256**,Xoshiro256**,DSFMT,PCG64,MT19937,Philox,ThreeFry
-    :widths: 14,14,14,14,14,14,14,14
-
-    32-bit Unsigned Ints,124,113,93,100,99,67,43
-    64-bit Unsigned Ints,174,133,100,118,100,83,44
-    Uniforms,212,181,229,147,100,91,57
-    Normals,438,382,291,304,264,252,190
-    Exponentials,851,770,547,601,512,467,275
-    Gammas,200,212,204,190,170,166,122
-    Binomials,114,112,123,101,93,91,81
-    Laplaces,122,123,127,114,105,103,93
-    Poissons,183,169,185,148,126,123,98
-    Overall,212,194,180,167,145,131,93
+    :header: ,PCG64,MT19937,Philox
+    :widths: 14,14,14,14
+
+    32-bit Unsigned Ints,100,99,67
+    64-bit Unsigned Ints,118,100,83
+    Uniforms,147,100,91
+    Normals,304,264,252
+    Exponentials,601,512,467
+    Gammas,190,170,166
+    Binomials,101,93,91
+    Laplaces,114,105,103
+    Poissons,148,126,123
+    Overall,167,145,131
 
 .. note::
 
@@ -81,33 +81,33 @@ across tables.
 64-bit Linux
 ~~~~~~~~~~~~
 
-===================  =======  =========  =======  ========  ==========  ============
-Distribution           DSFMT    MT19937    PCG64    Philox    ThreeFry    Xoshiro256
-===================  =======  =========  =======  ========  ==========  ============
-32-bit Unsigned Int     99.3        100    113.9      72.1        48.3         117.1
-64-bit Unsigned Int    105.7        100    143.3      89.7        48.1         161.7
-Uniform                222.1        100    181.5      90.8        59.9         204.7
-Exponential            110.8        100    145.5      92.5        55.0         177.1
-Normal                 113.2        100    121.4      98.3        71.9         162.0
-**Overall**            123.9        100    139.3      88.2        56.0         161.9
-===================  =======  =========  =======  ========  ==========  ============
+===================  =========  =======  ========
+Distribution           MT19937    PCG64    Philox
+===================  =========  =======  ========
+32-bit Unsigned Int        100    113.9      72.1
+64-bit Unsigned Int        100    143.3      89.7
+Uniform                    100    181.5      90.8
+Exponential                100    145.5      92.5
+Normal                     100    121.4      98.3
+**Overall**                100    139.3      88.2
+===================  =========  =======  ========
 
 
 64-bit Windows
 ~~~~~~~~~~~~~~
 The performance on 64-bit Linux and 64-bit Windows is broadly similar.
 
 
-===================  =======  =========  =======  ========  ==========  ============
-Distribution           DSFMT    MT19937    PCG64    Philox    ThreeFry    Xoshiro256
-===================  =======  =========  =======  ========  ==========  ============
-32-bit Unsigned Int    122.8        100    134.9      44.1        72.3         133.1
-64-bit Unsigned Int    130.4        100    162.7      41.0        77.7         142.3
-Uniform                273.2        100    200.0      44.8        84.6         175.8
-Exponential            135.0        100    167.8      47.4        84.5         166.9
-Normal                 115.3        100    135.6      60.3        93.6         169.6
-**Overall**            146.7        100    158.4      47.1        82.2         156.5
-===================  =======  =========  =======  ========  ==========  ============
+===================   =========  =======  ========
+Distribution            MT19937    PCG64    Philox
+===================   =========  =======  ========
+32-bit Unsigned Int         100    134.9      44.1
+64-bit Unsigned Int         100    162.7      41.0
+Uniform                     100    200.0      44.8
+Exponential                 100    167.8      47.4
+Normal                      100    135.6      60.3
+**Overall**                 100    158.4      47.1
+===================   =========  =======  ========
 
 32-bit Windows
 ~~~~~~~~~~~~~~
@@ -116,20 +116,20 @@ The performance of 64-bit generators on 32-bit Windows is much lower than on 64-
 operating systems due to register width. MT19937, the generator that has been
 in NumPy since 2005, operates on 32-bit integers.
 
-===================  =======  =========  =======  ========  ==========  ============
-Distribution           DSFMT    MT19937    PCG64    Philox    ThreeFry    Xoshiro256
-===================  =======  =========  =======  ========  ==========  ============
-32-bit Unsigned Int    110.9        100     30.6      28.1        29.2          74.4
-64-bit Unsigned Int    104.7        100     24.2      23.7        22.7          72.7
-Uniform                247.0        100     26.7      28.4        27.8          78.8
-Exponential            110.1        100     32.1      32.6        30.5          89.6
-Normal                 107.2        100     36.3      37.5        35.2          93.0
-**Overall**            127.6        100     29.7      29.7        28.8          81.3
-===================  =======  =========  =======  ========  ==========  ============
+===================  =========  =======  ========
+Distribution           MT19937    PCG64    Philox
+===================  =========  =======  ========
+32-bit Unsigned Int        100     30.6      28.1
+64-bit Unsigned Int        100     24.2      23.7
+Uniform                    100     26.7      28.4
+Exponential                100     32.1      32.6
+Normal                     100     36.3      37.5
+**Overall**                100     29.7      29.7
+===================  =========  =======  ========
 
 
 .. note::
 
-   Linux timings used Ubuntu 18.04 and GCC 7.4.  Windows timings were made on Windows 10
-   using Microsoft C/C++ Optimizing Compiler Version 19 (Visual Studio 2015). All timings
-   were produced on a i5-3570 processor.
+   Linux timings used Ubuntu 18.04 and GCC 7.4.  Windows timings were made on
+   Windows 10 using Microsoft C/C++ Optimizing Compiler Version 19 (Visual
+   Studio 2015). All timings were produced on a i5-3570 processor.