Merge pull request #95 from bashtage/fix-advance-docs

DOC: Update advance documentation

Author: bashtage

doc/source/multithreading.rst

@@ -14,7 +14,7 @@ which is fast, has a long period and supports using ``jump`` to advance the
 state. The random numbers generated are reproducible in the sense that the
 same seed will produce the same outputs.
 
-::
+.. code-block:: python
 
     import randomstate
     import multiprocessing

doc/source/parallel.rst

@@ -16,7 +16,7 @@ should be used.  This example shows how many streams can be created by
 passing in different index values in the second input while using the
 same seed in the first.
 
-::
+.. code-block:: python
 
   from randomstate.entropy import random_entropy
   import randomstate.prng.pcg64 as pcg64
@@ -32,6 +32,9 @@ same seed in the first.
 Jump/Advance the PRNG state
 ---------------------------
 
+Jump
+****
+
 ``jump`` advances the state of the PRNG *as-if* a large number of random
 numbers have been drawn.  The specific number of draws varies by PRNG, and
 ranges from :math:`2^{64}` to :math:`2^{512}`.  Additionally, the *as-if*
@@ -55,7 +58,7 @@ are listed below.
 ``jump`` can be used to produce long blocks which should be long enough to not
 overlap.
 
-::
+.. code-block:: python
 
   from randomstate.entropy import random_entropy
   import randomstate.prng.xorshift1024 as xorshift1024
@@ -70,7 +73,47 @@ overlap.
       blocks.append(block)
 
 
+Advance
+*******
 ``advance`` can be used to jump the state an arbitrary number of steps, and so
 is a more general approach than ``jump``.  Only ``pcg32`` and ``pcg64``
 support ``advance``, and since these also support independent streams, it is
 not usually necessary to use ``advance``.
+
+Advancing a PRNG updates the underlying PRNG state as-if a given number of
+calls to the underlying PRNG have been made. In general there is not a
+one-to-one relationship between the number output random values from a
+particular distribution and the number of draws from the core PRNG.
+This occurs for two reasons:
+
+* The random values are simulated using a rejection-based method
+  and so, on average, more than one value from the underlying
+  PRNG is required to generate an single draw.
+* The number of bits required to generate a simulated value
+  differs from the number of bits generated by the underlying
+  PRNG.  For example, two 16-bit integer values can be simulated
+  from a single draw of a 32-bit PRNG.
+
+Advancing the PRNG state resets any pre-computed random numbers. This is
+required to ensure exact reproducibility.
+
+This example uses ``advance`` to advance a ``pcg64`` generator 2 ** 127
+steps to set a sequence of random number generators.
+
+.. code-block:: python
+
+   import randomstate.prng.pcg64 as pcg64
+   rs = pcg64.RandomState()
+   rs_gen = pcg64.RandomState()
+   rs_gen.set_state(rs.get_state())
+
+   advance = 2**127
+   rngs = [rs]
+   for _ in range(9):
+       rs_gen.advance(advance)
+       rng = pcg64.RandomState()
+       rng.set_state(rs_gen.get_state())
+       rngs.append(rng)
+
+.. end block
+

randomstate/randomstate.pyx

@@ -417,12 +417,13 @@ cdef class RandomState:
             """
             advance(delta)
 
-            Advance the PRNG as-if delta drawn have occurred.
+            Advance the underlying PRNG as-if delta draws have occurred.
 
             Parameters
             ----------
             delta : integer, positive
-                Number of draws to advance the PRNG.
+                Number of draws to advance the PRNG. Must be less than the
+                size state variable in the underlying PRNG.
 
             Returns
             -------
@@ -431,7 +432,21 @@ cdef class RandomState:
 
             Notes
             -----
-            Advancing the prng state resets any pre-computed random numbers.
+            Advancing a PRNG updates the underlying PRNG state as-if a given
+            number of calls to the underlying PRNG have been made. In general
+            there is not a one-to-one relationship between the number output
+            random values from a particular distribution and the number of
+            draws from the core PRNG.  This occurs for two reasons:
+
+            * The random values are simulated using a rejection-based method
+              and so, on average, more than one value from the underlying
+              PRNG is required to generate an single draw.
+            * The number of bits required to generate a simulated value
+              differs from the number of bits generated by the underlying
+              PRNG.  For example, two 16-bit integer values can be simulated
+              from a single draw of a 32-bit PRNG.
+
+            Advancing the PRNG state resets any pre-computed random numbers.
             This is required to ensure exact reproducibility.
             """
             IF RS_RNG_MOD_NAME == 'pcg64':
@@ -1690,13 +1705,10 @@ cdef class RandomState:
     def complex_normal(self, loc=0.0, gamma=1.0, relation=0.0, size=None,
                        method=__normal_method):
         """
-        normal(loc=0.0, gamma=1.0, relation=0.0, size=None, method='bm')
+        complex_normal(loc=0.0, gamma=1.0, relation=0.0, size=None, method='bm')
 
         Draw random samples from a complex normal (Gaussian) distribution.
 
-        The complex normal is closely related to a bivariate normal
-        distribution where one of the dimensions is complex.
-
         Parameters
         ----------
         loc : complex or array_like of complex
@@ -1729,7 +1741,7 @@ cdef class RandomState:
         Notes
         -----
         **EXPERIMENTAL** Not part of official NumPy RandomState, may change until
-        formal release on PyPi
+        formal release on PyPi.
         
         Complex normals are generated from a bivariate normal where the
         variance of the real component is 0.5 Re(gamma + relation), the