FIX: Add jump and advance to module base

Add jump and advance to module base where available
Improve doc strings to explain how to use PRNG in parallel
Rename C-functions advnace and jump to avoid conflicts

Author: Sheppard, Kevin

randomstate/defaults.pxi

@@ -0,0 +1,5 @@
+DEF RS_NORMAL_METHOD = 'zig'
+DEF RS_RNG_SEED = 1
+DEF RS_RNG_ADVANCEABLE = 0
+DEF RS_RNG_JUMPABLE = 0
+DEF RS_RNG_STATE_LEN = 4

randomstate/interface.pyx

@@ -316,11 +316,11 @@ cdef class RandomState:
             """
             IF RNG_NAME == 'pcg64':
                 IF PCG128_EMULATED:
-                    advance(&self.rng_state, pcg128_from_pylong(delta))
+                    advance_state(&self.rng_state, pcg128_from_pylong(delta))
                 ELSE:
-                    advance(&self.rng_state, delta)
+                    advance_state(&self.rng_state, delta)
             ELSE:
-                advance(&self.rng_state, delta)
+                advance_state(&self.rng_state, delta)
 
             self.rng_state.has_gauss = 0
             self.rng_state.gauss = 0.0
@@ -351,7 +351,7 @@ cdef class RandomState:
             """
             cdef Py_ssize_t i;
             for i in range(iter):
-                jump(&self.rng_state)
+                jump_state(&self.rng_state)
             self.rng_state.has_gauss = 0
             self.rng_state.gauss = 0.0
             return None
@@ -4225,4 +4225,9 @@ dirichlet = _rand.dirichlet
 shuffle = _rand.shuffle
 permutation = _rand.permutation
 
-sample = ranf = random = random_sample
+sample = ranf = random = random_sample
+
+IF RNG_JUMPABLE:
+    jump = _rand.jump
+IF RNG_ADVANCEABLE:
+    advance = _rand.advance

randomstate/shims/dSFMT/dSFMT.pxi

@@ -92,7 +92,8 @@ value is generated and returned. If `size` is an integer, then a 1-D
 array filled with generated values is returned. If `size` is a tuple,
 then an array with that shape is filled and returned.
 
-*No Compatibility Guarantee*
+**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
 parameters will always produce the same results. This is different from

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

@@ -71,7 +71,8 @@ value is generated and returned. If `size` is an integer, then a 1-D
 array filled with generated values is returned. If ``size`` is a tuple,
 then an array with that shape is filled and returned.
 
-*No Compatibility Guarantee*
+**No Compatibility Guarantee**
+
 ``mlfg_1279_861.RandomState`` does not make a guarantee that a fixed seed and a
 fixed series of calls to 'mlfg_1279_861.RandomState' methods using the same
 parameters will always produce the same results. This is different from

randomstate/shims/mrg32k3a/mrg32k3a.pxi

@@ -63,7 +63,8 @@ value is generated and returned. If `size` is an integer, then a 1-D
 array filled with generated values is returned. If `size` is a tuple,
 then an array with that shape is filled and returned.
 
-*No Compatibility Guarantee*
+**No Compatibility Guarantee**
+
 ``mrg32k3a.RandomState`` does not make a guarantee that a fixed seed and a
 fixed series of calls to ``mrg32k3a.RandomState`` methods using the same
 parameters will always produce the same results. This is different from

randomstate/shims/pcg-32/pcg-32-shim.c

@@ -6,7 +6,7 @@ extern inline uint64_t random_uint64(aug_state* state);
 
 extern inline void set_seed(aug_state* state, uint64_t seed, uint64_t inc);
 
-extern inline void advance(aug_state* state, uint64_t delta);
+extern inline void advance_state(aug_state* state, uint64_t delta);
 
 extern inline void entropy_init(aug_state* state);
 

randomstate/shims/pcg-32/pcg-32-shim.h

@@ -32,7 +32,7 @@ inline void set_seed(aug_state* state, uint64_t seed, uint64_t inc)
     pcg32_srandom_r(state->rng, seed, inc);
 }
 
-inline void advance(aug_state* state, uint64_t delta)
+inline void advance_state(aug_state* state, uint64_t delta)
 {
     pcg32_advance_r(state->rng, delta);
 }

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

@@ -25,7 +25,7 @@ cdef extern from "distributions.h":
 
     cdef void set_seed(aug_state* state, uint64_t seed, uint64_t inc)
 
-    cdef void advance(aug_state* state, uint64_t delta)
+    cdef void advance_state(aug_state* state, uint64_t delta)
 
 ctypedef uint64_t rng_state_t
 
@@ -55,7 +55,8 @@ value is generated and returned. If `size` is an integer, then a 1-D
 array filled with generated values is returned. If `size` is a tuple,
 then an array with that shape is filled and returned.
 
-*No Compatibility Guarantee*
+**No Compatibility Guarantee**
+
 ``pcg32.RandomState`` does not make a guarantee that a fixed seed and a
 fixed series of calls to ``pcg32.RandomState`` methods using the same
 parameters will always produce the same results. This is different from
@@ -84,6 +85,26 @@ The state of the PCG-32 PRNG is represented by 2 64-bit unsigned integers.
 
 See pcg64 for a similar implementation with a larger period.
 
+** Parallel Features **
+
+``pcg32.RandomState`` can be used in parallel applications in one of two ways.
+The preferable method is to use sub-streams, which are generated by using the
+same value in the first position of the seed and incrementing the second value.
+
+>>> import randomstate.prng.pcg32 as rnd
+>>> rs = [rng.RandomState(1234, i + 1) for i in range(10)]
+
+The alternative method is to use a single RandomState and advance to get
+non-overlapping sequences.
+
+>>> import randomstate.prng.pcg32 as rnd
+>>> rs = [rng.RandomState(1234, 1) for _ in range(10)]
+>>> for i in range(10):
+        rs[i].advance(2**32)
+
+*Note*: Due to the limited period of ``pcg32.RandomState``  using ``advance``
+in parallel applications is not recommended.
+
 References
 ----------
 .. [1] "PCG, A Family of Better Random Number Generators",

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

@@ -15,7 +15,8 @@ value is generated and returned. If `size` is an integer, then a 1-D
 array filled with generated values is returned. If `size` is a tuple,
 then an array with that shape is filled and returned.
 
-*No Compatibility Guarantee*
+**No Compatibility Guarantee**
+
 ``pcg64.RandomState`` does not make a guarantee that a fixed seed and a
 fixed series of calls to ``pcg64.RandomState`` methods using the same
 parameters will always produce the same results. This is different from
@@ -44,6 +45,23 @@ The state of the PCG-64 PRNG is represented by 2 128-bit unsigned integers.
 
 See pcg32 for a similar implementation with a smaller period.
 
+** Parallel Features **
+
+``pcg64.RandomState`` can be used in parallel applications in one of two ways.
+The preferable method is to use sub-streams, which are generated by using the
+same value in the first position of the seed and incrementing the second value.
+
+>>> import randomstate.prng.pcg64 as rnd
+>>> rs = [rng.RandomState(1234, i + 1) for i in range(10)]
+
+The alternative method is to use a single RandomState and advance to get
+non-overlapping sequences.
+
+>>> import randomstate.prng.pcg64 as rnd
+>>> rs = [rng.RandomState(1234, 1) for _ in range(10)]
+>>> for i in range(10):
+        rs[i].advance(2**32)
+
 References
 ----------
 .. [1] "PCG, A Family of Better Random Number Generators",

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

@@ -31,7 +31,7 @@ cdef extern from "distributions.h":
 
     ctypedef s_aug_state aug_state
 
-    cdef void advance(aug_state* state, pcg128_t delta)
+    cdef void advance_state(aug_state* state, pcg128_t delta)
 
     cdef void set_seed(aug_state* state, pcg128_t seed, pcg128_t inc)