Skip to content

Commit

Permalink
DOC: fixup docs for current set of BitGenerators
Browse files Browse the repository at this point in the history
  • Loading branch information
@mattip
mattip committed Jun 26, 2019
1 parent 0897a68 commit 5c5965c
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 81 deletions.
25 changes: 23 additions & 2 deletions doc/source/reference/random/bit_generators/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand All @@ -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
Expand Down
22 changes: 0 additions & 22 deletions doc/source/reference/random/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
114 changes: 57 additions & 57 deletions doc/source/reference/random/performance.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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
~~~~~~~~~~~~~~
Expand All @@ -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.

0 comments on commit 5c5965c

Please sign in to comment.