Skip to content

Commit

Permalink
DOC: Fix PRNG doc strings
Browse files Browse the repository at this point in the history
Improve PRNG doc strings
Add Jump docstring for MT19937
  • Loading branch information
bashtage committed Aug 2, 2017
1 parent 8bd5a71 commit a8ac5f4
Show file tree
Hide file tree
Showing 5 changed files with 69 additions and 17 deletions.
2 changes: 2 additions & 0 deletions randomstate/interface/dSFMT/dSFMT.pxi
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,8 @@ 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.
References
----------
.. [1] Mutsuo Saito and Makoto Matsumoto, "SIMD-oriented Fast Mersenne
Twister: a 128-bit Pseudorandom Number Generator." Monte Carlo
and Quasi-Monte Carlo Methods 2006, Springer, pp. 607 -- 622, 2008.
Expand Down
57 changes: 50 additions & 7 deletions randomstate/interface/random-kit/random-kit.pxi
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,6 @@ 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.
``mt19937.RandomState`` 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.
Parameters
----------
seed : {None, int, array_like}, optional
Expand All @@ -96,4 +89,54 @@ pseudo-random number generator with a number of methods that are similar
to the ones available in ``RandomState``. ``RandomState``, besides being
NumPy-aware, has the advantage that it provides a much larger number
of probability distributions to choose from.
**Parallel Features**
``mt19937.RandomState`` 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.
>>> from randomstate.entropy import random_entropy
>>> import randomstate.prng.mt19937 as rnd
>>> seed = random_entropy()
>>> rs = [rnd.RandomState(seed) for _ in range(10)]
# Advance rs[i] by i jumps
>>> for i in range(10):
rs[i].jump(i)
References
----------
.. [1] Hiroshi Haramoto, Makoto Matsumoto, and Pierre L\'Ecuyer, "A Fast
Jump Ahead Algorithm for Linear Recurrences in a Polynomial Space",
Sequences and Their Applications - SETA, 290--298, 2008.
.. [2] Hiroshi Haramoto, Makoto Matsumoto, Takuji Nishimura, François
Panneton, Pierre L\'Ecuyer, "Efficient Jump Ahead for F2-Linear
Random Number Generators", INFORMS JOURNAL ON COMPUTING, Vol. 20,
No. 3, Summer 2008, pp. 385-390.
"""

DEF JUMP_DOCSTRING = u"""
jump(iter = 1)
Jumps the state of the random number generator as-if 2**128 random numbers
have been generated.
Parameters
----------
iter : integer, positive
Number of times to jump the state of the prng.
Returns
-------
out : None
Returns 'None' on success.
Notes
-----
Jumping the rng state resets any pre-computed random numbers. This is required
to ensure exact reproducibility.
"""
13 changes: 9 additions & 4 deletions randomstate/interface/sfmt/sfmt.pxi
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ RandomState(seed=None)
Container for the SIMD-based Mersenne Twister pseudo-random number generator.
``dSFMT.RandomState`` exposes a number of methods for generating random
``sfmt.RandomState`` exposes a number of methods for generating random
numbers drawn from a variety of probability distributions [1]_ . 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
Expand All @@ -91,8 +91,8 @@ then an array with that shape is filled and returned.
**No Compatibility Guarantee**
``dSFMT.RandomState`` does not make a guarantee that a fixed seed and a
fixed series of calls to ``dSFMT.RandomState`` methods using the same
``sfmt.RandomState`` does not make a guarantee that a fixed seed and a
fixed series of calls to ``sfmt.RandomState`` methods using the same
parameters will always produce the same results. This is different from
``numpy.random.RandomState`` guarantee. This is done to simplify improving
random number generators. To ensure identical results, you must use the
Expand All @@ -104,7 +104,7 @@ 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.RandomState`` will try to read entropy from
then ``sfmt.RandomState`` will try to read entropy from
``/dev/urandom`` (or the Windows analog) if available to
produce a 64-bit seed. If unavailable, the a 64-bit hash of the time
and process ID is used.
Expand Down Expand Up @@ -154,9 +154,14 @@ 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.
References
----------
.. [1] Mutsuo Saito and Makoto Matsumoto, "SIMD-oriented Fast Mersenne
Twister: a 128-bit Pseudorandom Number Generator." Monte Carlo
and Quasi-Monte Carlo Methods 2006, Springer, pp. 607 -- 622, 2008.
.. [2] Hiroshi Haramoto, Makoto Matsumoto, and Pierre L\'Ecuyer, "A Fast
Jump Ahead Algorithm for Linear Recurrences in a Polynomial Space",
Sequences and Their Applications - SETA, 290--298, 2008.
"""

DEF JUMP_DOCSTRING = u"""
Expand Down
7 changes: 4 additions & 3 deletions randomstate/interface/xorshift1024/xorshift1024.pxi
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,10 @@ RandomState(seed=None)
Container for the xorshift1024* pseudo-random number generator.
xorshift1024* is a 64-bit implementation of Saito and Matsumoto's XSadd
generator [1]_. xorshift1024* has a period of :math:`2^{1024} - 1` and
supports jumping the sequence in increments of :math:`2^{512}`, which allows
multiple non-overlapping sequences to be generated.
generator [1]_ (see also [2]_, [3]_, [4]_). xorshift1024* has a period of
:math:`2^{1024} - 1` and supports jumping the sequence in increments of
:math:`2^{512}`, which allows multiple non-overlapping sequences to be
generated.
``xorshift1024.RandomState`` exposes a number of methods for generating random
numbers drawn from a variety of probability distributions. In addition to the
Expand Down
7 changes: 4 additions & 3 deletions randomstate/interface/xorshift128/xorshift128.pxi
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,10 @@ RandomState(seed=None)
Container for the xorshift128+ pseudo-random number generator.
xorshift128+ is a 64-bit implementation of Saito and Matsumoto's XSadd
generator [1]_. xorshift128+ has a period of :math:`2^{128} - 1` and
supports jumping the sequence in increments of :math:`2^{64}`, which allows
multiple non-overlapping sequences to be generated.
generator [1]_ (see also [2]_, [3]_, [4]_). xorshift128+ has a period of
:math:`2^{128} - 1` and supports jumping the sequence in increments of
:math:`2^{64}`, which allows multiple non-overlapping sequences to be
generated.
``xorshift128.RandomState`` exposes a number of methods for generating random
numbers drawn from a variety of probability distributions. In addition to the
Expand Down

0 comments on commit a8ac5f4

Please sign in to comment.