DOC: Add PRNG implementation details

Add details of all PRNG implementaions as well as state info

[skip ci]

Author: bashtage

compute_mod3.py

@@ -0,0 +1,6 @@
+import pandas as pd
+import numpy as np
+import seaborn as sns
+
+sns.mpl.rcParams['figure.figsize'] = [12, 8]
+

randomstate/shims/dSFMT/dSFMT.pxi

@@ -140,6 +140,7 @@ segments come from the same sequence.
         rs[i].jump(i)
 
 **State and Seeding**
+
 The ``dsfmt.RandomState`` state vector consists of a 764 element array of
 32-bit unsigned integers plus a single integer value between 0 and 382
 indicating  the current position within the main array. The implementation

randomstate/shims/mlfg-1279-861/mlfg-1279-861.pxi

@@ -94,12 +94,14 @@ integers as well as a two 32-bit integers representing the location in the
 state array of the current and lagged values.
 
 **State and Seeding**
-The ``dsfmt.mlfg_1279_861`` state vector consists of a 1279 element array of
-64-bit unsigned integers plus a two integers value between 0 and 1278
-indicating  the current position and the lagged value within the main array
-required to produce the next random.
 
-``dsfmt.mlfg_1279_861`` is seeded using either a single 64-bit unsigned integer
+The ``mlfg_1279_861.RandomState`` state vector consists of a 1279 element array
+of 64-bit unsigned integers plus a two integers value between 0 and 1278
+indicating  the current position and the position of the lagged value within
+the main array required to produce the next random. All elements of the 1279
+element state array must be odd.
+
+``mlfg_1279_861.RandomState`` is seeded using either a single 64-bit unsigned integer
 or a vector of 64-bit unsigned integers.  In either case the input seed is
 used as an input (or inputs) for another simple random number generator,
 Splitmix64, and the output of this PRNG function is used as the initial state.
@@ -108,5 +110,5 @@ the possible initial state values.  When using an array, the SplitMix64 state
 for producing the ith component of the initial state is XORd with the ith
 value of the seed array until the seed array is exhausted. When using an array
 the initial state for the SplitMix64 state is 0 so that using a single element
-array and using a single scalar value will produce the same initial state.
+array and using the same value as a scalar will produce the same initial state.
 """

randomstate/shims/mrg32k3a/mrg32k3a.pxi

@@ -161,6 +161,24 @@ seed to ensure that the segments come from the same sequence.
 >>> for i in range(10):
         rs[i].jump(i)
 
+**State and Seeding**
+
+The ``mrg32k3a.RandomState`` state vector consists of a 6 element array
+of 64-bit signed integers plus a single integers value between 0 and 2
+indicating  the current position within the state vector.  The first three
+elements of the state vector are in [0, 4294967087) and the second 3 are
+in [0, 4294944443).
+
+``mrg32k3a.RandomState`` is seeded using either a single 64-bit unsigned integer
+or a vector of 64-bit unsigned integers.  In either case the input seed is
+used as an input (or inputs) for another simple random number generator,
+Splitmix64, and the output of this PRNG function is used as the initial state.
+Using a single 64-bit value for the seed can only initialize a small range of
+the possible initial state values.  When using an array, the SplitMix64 state
+for producing the ith component of the initial state is XORd with the ith
+value of the seed array until the seed array is exhausted. When using an array
+the initial state for the SplitMix64 state is 0 so that using a single element
+array and using the same value as a scalar will produce the same initial state.
 
 References
 ----------

randomstate/shims/pcg-32/pcg-32.pxi

@@ -102,6 +102,12 @@ produce non-overlapping sequences.
 *Note*: Due to the limited period of ``pcg32.RandomState``  using ``advance``
 in parallel applications is not recommended.
 
+**State and Seeding**
+
+The ``pcg32.RandomState`` state vector consists of 2 unsigned 64 bit values.
+``pcg32.RandomState`  is seeded using a single 64-bit unsigned integer.
+In addition, a second 64-bit unsigned integer is used to set the stream.
+
 References
 ----------
 .. [1] "PCG, A Family of Better Random Number Generators",

randomstate/shims/pcg-64/pcg-64-docstring.pxi

@@ -62,6 +62,14 @@ produce non-overlapping sequences.
 >>> for i in range(10):
         rs[i].advance(i * 2**64)
 
+**State and Seeding**
+
+The ``pcg64.RandomState`` state vector consists of 2 unsigned 128 bit values,
+which are represented externally as python longs (2.x) or ints (Python 3+).
+``pcg64.RandomState` is seeded using a single 128-bit unsigned integer
+(Python long/int). In addition, a second 128-bit unsigned integer is used
+to set the stream.
+
 References
 ----------
 .. [1] "PCG, A Family of Better Random Number Generators",

randomstate/shims/xorshift1024/xorshift1024.pxi

@@ -102,6 +102,22 @@ seed to ensure that the segments come from the same sequence.
 >>> for i in range(10):
         rs[i].jump(i)
 
+**State and Seeding**
+
+The ``xorshift1024.RandomState`` state vector consists of a 16 element array
+of 64-bit unsigned integers.
+
+``xorshift1024.RandomState`` is seeded using either a single 64-bit unsigned integer
+or a vector of 64-bit unsigned integers.  In either case the input seed is
+used as an input (or inputs) for another simple random number generator,
+Splitmix64, and the output of this PRNG function is used as the initial state.
+Using a single 64-bit value for the seed can only initialize a small range of
+the possible initial state values.  When using an array, the SplitMix64 state
+for producing the ith component of the initial state is XORd with the ith
+value of the seed array until the seed array is exhausted. When using an array
+the initial state for the SplitMix64 state is 0 so that using a single element
+array and using the same value as a scalar will produce the same initial state.
+
 References
 ----------
 .. [1] "xorshift*/xorshift+ generators and the PRNG shootout",

randomstate/shims/xorshift128/xorshift128.pxi

@@ -98,6 +98,22 @@ seed to ensure that the segments come from the same sequence.
 >>> for i in range(10):
         rs[i].jump(i)
 
+**State and Seeding**
+
+The ``xorshift128.RandomState`` state vector consists of a 2 element array
+of 64-bit unsigned integers.
+
+``xorshift128.RandomState`` is seeded using either a single 64-bit unsigned integer
+or a vector of 64-bit unsigned integers.  In either case the input seed is
+used as an input (or inputs) for another simple random number generator,
+Splitmix64, and the output of this PRNG function is used as the initial state.
+Using a single 64-bit value for the seed can only initialize a small range of
+the possible initial state values.  When using an array, the SplitMix64 state
+for producing the ith component of the initial state is XORd with the ith
+value of the seed array until the seed array is exhausted. When using an array
+the initial state for the SplitMix64 state is 0 so that using a single element
+array and using the same value as a scalar will produce the same initial state.
+
 References
 ----------
 .. [1] "xorshift*/xorshift+ generators and the PRNG shootout",