Merge pull request #38 from IntelPython/fill-out-how-to

Filled out how_to.rst, added labels for BRNG pages.

docs/source/how_to.rst

@@ -1,4 +1,87 @@
 How-to Guides
 =============
 
-To be written.
+How to save and resume long computation
+---------------------------------------
+
+:class:`RandomState` is pickleable, and pickling allows to save and restore
+the internal state of the quasi-random number generators.
+
+.. code-block:: python
+    :caption: Saving state of quasi-random basic random number generators
+
+        import numpy as np
+        import mkl_random
+        import pickle
+
+        rs = mkl_random.RandomState(seed=777, brng="r250")
+        draw = rs.standard_normal(size=1357913)
+
+        # pickle random state
+        saved = pickle.dumps(rs)
+
+        # draw some numbers as if computation were to continue
+        post_draw = rs.gamma(5, 1, size=100)
+
+        # restore random state, and continue from 
+        restored_rs = pickle.loads(saved)
+        resumed_draw = restored_rs.gamma(5, 1, size=100)
+        
+        # sample from restored stated is the same as sample 
+        # from the original one
+        assert np.array_equal(restored_rs, resumed_draw)
+
+
+Stochastic computations in parallel with multiprocessing
+--------------------------------------------------------
+
+When performing stochastic computations in parallel, care is due to ensure
+statistical independence of samples drawn in parallel.
+
+Basic quasi-random number generators provide different means to accomplishing
+this. Some support :meth:`skipahead` method or :meth:`leapfrog` method, while
+others provide a fixed-size family of generators with nice property that generators
+from such family, initialized equally, produce streams of randomness statistically
+indistunguishable from independent.
+
+.. py:method:: skipahead(nskips)
+    :canonical: mkl_random.RandomState.skipahead
+
+    Advance the state of the generator using skip-ahead method, or raise :code:`ValueError` 
+    exception if not supported. 
+
+    The argument `nskips` must be a positive Python integer.
+
+    The method is supported for :ref:`"philox4x32x10" <philox4x32x10_brng>`, :ref:`"mrg32k3a" <mrg32k3a_brng>`, 
+    :ref:`"mcg31m1" <mcg31m1_brng>`, :ref:`"mcg59" <mcg59_brng>`, :ref:`"wh" <wh_brng>`,
+    :ref:`"mt19937" <mt19937_brng>`, :ref:`"sfmt19937" <sfmt19937_brng>`, and :ref:`"ars5" <ars5_brng>` 
+    basic random number generators.
+
+.. note::
+    When using :meth:`skipahead`, it is important to ensure that a parallel task does not consume more than
+    :code:`nskips` states, otherwise streams of randomness begin to overlap and the assumption of statistical
+    independence breaks down.
+
+.. py:method:: leapfrog(k, nstreams)
+    :canonical: mkl_random.RandomState.leapfrog
+
+    Initialize the state of the generator using leap-frog method, or raise :code:`ValueError`
+    exception if not supported.
+
+    The leap-frog method partitions state tragectory into :code:`nstream` interleaved non-overlapping 
+    sub-sequences, and argument :code:`k` identifies the subsequence.
+
+    The method is supported for :ref:`"mcg31m1" <mcg31m1_brng>`, :ref:`"mcg59" <mcg59_brng>`, and :ref:`"wh" <wh_brng>` 
+    basic pseudo-random number generators.
+
+.. note::
+    When using :meth:`leapfrog` or :meth:`skipahead` methods one must remember that parallel tasks partition 
+    generators period and choose a generator with sufficiently long period to avoid cycling over the period 
+    more than once, as doing so also breaks the assumption of statistical independence and may compromise
+    correctness of the simulation.
+
+:mod:`mkl_random` also provides two families of basic pseudo-random number generators, :ref:`"mt2203" <mt2203_brng>` and
+:ref:`"wh" <wh_brng>`, with property that members from particular family, initialized equally, produce streams of 
+randomness stasistically indistunguishable from independent. To use such families in parallel computation, assign
+difference family generators to different parallel workers and sample those assigned generators in each parallel worker.
+Please refer to "examples/" folder in the `GitHub repo <https://github.com/IntelPython/mkl_random>`_ for more details.

docs/source/reference/ars5.rst

@@ -1,3 +1,5 @@
+.. _ars5_brng:
+
 ARS5 brng
 =========
 

docs/source/reference/mcg31.rst

@@ -1,3 +1,5 @@
+.. _mcg31m1_brng:
+
 MCG31 brng
 ==========
 

docs/source/reference/mcg59.rst

@@ -1,3 +1,5 @@
+.. _mcg59_brng:
+
 MCG59 brng
 ==========
 

docs/source/reference/mrg32k3a.rst

@@ -1,3 +1,5 @@
+.. _mrg32k3a_brng:
+
 MRG32k3a brng
 =============
 

docs/source/reference/mt19937.rst

@@ -1,3 +1,5 @@
+.. _mt19937_brng:
+
 MT19937 brng
 ============
 

docs/source/reference/mt2203.rst

@@ -1,3 +1,5 @@
+.. _mt2203_brng:
+
 MT2203 brng
 ===========
 

docs/source/reference/nondeterministic.rst

@@ -1,3 +1,5 @@
+.. _nondeterm_brng:
+
 Nondeterm brng
 ==============
 

docs/source/reference/philox4x32x10.rst

@@ -1,3 +1,5 @@
+.. _philox4x32x10_brng:
+
 Philox4x32x10 brng
 ==================
 

docs/source/reference/r250.rst

@@ -1,3 +1,5 @@
+.. _r250_brng:
+
 R250 brng
 =========
 

docs/source/reference/sfmt19937.rst

@@ -1,3 +1,5 @@
+.. _sfmt19937_brng:
+
 SFMT19937 brng
 ==============
 

docs/source/reference/wichmann_hill.rst

@@ -1,3 +1,5 @@
+.. _wh_brng:
+
 Wichmann-Hill brng
 ==================
 

docs/source/tutorials.rst

@@ -1,5 +1,8 @@
+Beginner's guide
+================
+
 Installation
-============
+------------
 
 Package :mod:`mkl_random` is available in conda ecosystem on "conda-forge", default, and "intel" channels.
 
@@ -32,8 +35,8 @@ The package can also be installed via :code:`pip`, either from PyPI, or from
 
 The :mod:`mkl_random` is also distributed as part of `Intel(R) Distribution for Python* <https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-python.html>`_.
 
-Beginner's guide
-================
+First steps
+-----------
 
 The :mod:`mkl_random` package was designed following :class:`numpy.random.RandomState` class to 
 make use of :mod:`mkl_random` easy for current uses of :mod:`numpy.random` module.