From a8ac5f4572270696137413947cd36513f9d8e6ed Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Wed, 2 Aug 2017 18:53:22 +0100 Subject: [PATCH] DOC: Fix PRNG doc strings Improve PRNG doc strings Add Jump docstring for MT19937 --- randomstate/interface/dSFMT/dSFMT.pxi | 2 + .../interface/random-kit/random-kit.pxi | 57 ++++++++++++++++--- randomstate/interface/sfmt/sfmt.pxi | 13 +++-- .../interface/xorshift1024/xorshift1024.pxi | 7 ++- .../interface/xorshift128/xorshift128.pxi | 7 ++- 5 files changed, 69 insertions(+), 17 deletions(-) diff --git a/randomstate/interface/dSFMT/dSFMT.pxi b/randomstate/interface/dSFMT/dSFMT.pxi index 548a916e..018355c9 100644 --- a/randomstate/interface/dSFMT/dSFMT.pxi +++ b/randomstate/interface/dSFMT/dSFMT.pxi @@ -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. diff --git a/randomstate/interface/random-kit/random-kit.pxi b/randomstate/interface/random-kit/random-kit.pxi index ee1af493..123bd2ac 100644 --- a/randomstate/interface/random-kit/random-kit.pxi +++ b/randomstate/interface/random-kit/random-kit.pxi @@ -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 @@ -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. """ \ No newline at end of file diff --git a/randomstate/interface/sfmt/sfmt.pxi b/randomstate/interface/sfmt/sfmt.pxi index 3936d0cf..77210b22 100644 --- a/randomstate/interface/sfmt/sfmt.pxi +++ b/randomstate/interface/sfmt/sfmt.pxi @@ -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 @@ -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 @@ -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. @@ -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""" diff --git a/randomstate/interface/xorshift1024/xorshift1024.pxi b/randomstate/interface/xorshift1024/xorshift1024.pxi index c4688d03..d66affa8 100644 --- a/randomstate/interface/xorshift1024/xorshift1024.pxi +++ b/randomstate/interface/xorshift1024/xorshift1024.pxi @@ -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 diff --git a/randomstate/interface/xorshift128/xorshift128.pxi b/randomstate/interface/xorshift128/xorshift128.pxi index 90db417e..0504abdf 100644 --- a/randomstate/interface/xorshift128/xorshift128.pxi +++ b/randomstate/interface/xorshift128/xorshift128.pxi @@ -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