Merge pull request #25 from bashtage/gh-pages

DOC: Improve documentation

Author: bashtage

doc/source/entropy.rst

@@ -0,0 +1,4 @@
+System Entropy
+==============
+
+.. autofunction:: randomstate.entropy.random_entropy

doc/source/index.rst

@@ -1,7 +1,57 @@
 randomstate's documentation
 ===========================
+This package contains a drop-in replacements for the NumPy RandomState object
+that change the core random number generator.
 
-RnadomPseudo Random Number Generator Documentation:
+What's New or Different
+=======================
+* ``random_uintegers`` produces either 32-bit or 64-bit unsigned integers.
+  These are at thte core of most PRNGs and so they are directly exposed.
+* ``randomstate.entropy.random_entropy`` provides access to the system
+  source of randomness that is used in cryptographic applications (e.g.,
+  ``/dev/urandom`` on Unix).
+* The normal generator supports a 256-step ziggurat method which is 2-6 times
+  faster than NumPy's ``standard_normal``.  This generator can be accessed using
+
+.. code-block:: python
+
+  from randomstate import standard_normal
+  standard_normal(100000, method='zig')
+
+
+Supported Generators
+====================
+The main innovation is the includion of a number of alterntive pseudo random number
+generators, 'in addition' to the standard PRNG in NumPy.  The included PRNGs are:
+
+* MT19937 - The standard NumPy generator.  Produces identical results to NumPy
+  using the same seed/state. See `NumPy's documentation`_.
+* dSFMT - A SSE2 enables version of the MT19937 generator.  Theoretically the
+  same, but with a different state and so it is not possible to produce an
+  sequence identical to MT19937. See the `dSFMT authors' page`_.
+* XorShit128+ and XorShift1024* - Vast fast generators based on the XSadd
+  generator. These generators can be rapidly 'jumped' and so can be used in
+  parallel applications. See the `xorshift authors' page`_.
+* PCG-32 and PCG-64 - Fast generators that support many parallel streams and
+  can be advanced by an arbitrary amount. PCG-32 only as a period of  :math:`2^{64}`
+  while PCG-64 has a period of :math:`2^{128}`. See the `PCG author's page`_.
+* Multiplicative Lagged Fibbonacci Generator MLFG(1279, 861, \*) - A directly
+  implemented multiplicative lagged fibbonacci generator with a very large
+  period and good performance. Future plans include multiple stream support.
+  See the `wiki page on Fibonacci generators`_.
+* MRG32K3A - a classic and popular generator by L'Ecuyer. Future plans
+  include multiple stream support. See the `MRG32K3A author's page`_. Lower
+  performance than more modern generators.
+
+.. _`NumPy's documentation`: http://docs.scipy.org/doc/numpy/reference/routines.random.html
+.. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/
+.. _`xorshift authors' page`:  http://xorshift.di.unimi.it/
+.. _`PCG author's page`: http://www.pcg-random.org/
+.. _`wiki page on Fibonacci generators`: https://en.wikipedia.org/wiki/Lagged_Fibonacci_generator
+.. _`MRG32K3A author's page`: http://simul.iro.umontreal.ca/
+
+
+RandomState Pseudo Random Number Generator Documentation:
 
 .. toctree::
    :maxdepth: 2
@@ -14,10 +64,8 @@ RnadomPseudo Random Number Generator Documentation:
    PCG-64 <pcg64>
    MLFG <mlfg>
    MRG32K3A <mrg32k3a>
+   Readying System Entropy <entropy>
 
-Other Functions
-===============
-.. autofunction:: randomstate.entropy.random_entropy
 
 Indices and tables
 ==================

doc/source/mlfg.rst

@@ -1,5 +1,5 @@
-MLFG(1279, 861, *)  Randomstate
-===============================
+MLFG(1279, 861, \*)  Randomstate
+================================
 
 .. py:currentmodule:: randomstate.prng.mlfg_1279_861
 

randomstate/interface.pyx

@@ -178,13 +178,13 @@ cdef class RandomState:
 
             Seed the generator.
 
-            This method is called when `RandomState` is initialized. It can be
-            called again to re-seed the generator. For details, see `RandomState`.
+            This method is called when ``RandomState`` is initialized. It can be
+            called again to re-seed the generator. For details, see ``RandomState``.
 
             Parameters
             ----------
             seed : int or array_like, optional
-                Seed for `RandomState`.
+                Seed for ``RandomState``.
                 Must be convertible to 32 bit unsigned integers.
 
             See Also
@@ -219,13 +219,13 @@ cdef class RandomState:
 
             Seed the generator.
 
-            This method is called when `RandomState` is initialized. It can be
-            called again to re-seed the generator. For details, see `RandomState`.
+            This method is called when ``RandomState`` is initialized. It can be
+            called again to re-seed the generator. For details, see ``RandomState``.
 
             Parameters
             ----------
             val : int, optional
-                Seed for `RandomState`.
+                Seed for ``RandomState``.
 
             Notes
             -----
@@ -253,13 +253,13 @@ cdef class RandomState:
 
             Seed the generator.
 
-            This method is called when `RandomState` is initialized. It can be
-            called again to re-seed the generator. For details, see `RandomState`.
+            This method is called when ``RandomState`` is initialized. It can be
+            called again to re-seed the generator. For details, see ``RandomState``.
 
             Parameters
             ----------
             val : int, optional
-                Seed for `RandomState`.
+                Seed for ``RandomState``.
             inc : int, optional
                 Increment to use for producing multiple streams
 
@@ -363,7 +363,7 @@ cdef class RandomState:
 
             Return a tuple representing the internal state of the generator.
 
-            For more details, see `set_state`.
+            For more details, see ``set_state``.
 
             Parameters
             ----------
@@ -386,7 +386,7 @@ cdef class RandomState:
 
             Notes
             -----
-            `set_state` and `get_state` are not needed to work with any of the
+            ``set_state`` and ``get_state`` are not needed to work with any of the
             random distributions in NumPy. If the internal state is manually altered,
             the user should know exactly what he/she is doing.
 
@@ -410,7 +410,7 @@ cdef class RandomState:
 
             Return a tuple representing the internal state of the generator.
 
-            For more details, see `set_state`.
+            For more details, see ``set_state``.
 
             Returns
             -------
@@ -428,7 +428,7 @@ cdef class RandomState:
 
             Notes
             -----
-            `set_state` and `get_state` are not needed to work with any of the
+            ``set_state`` and ``get_state`` are not needed to work with any of the
             random distributions in NumPy. If the internal state is manually altered,
             the user should know exactly what he/she is doing.
 
@@ -471,7 +471,7 @@ cdef class RandomState:
 
         Notes
         -----
-        `set_state` and `get_state` are not needed to work with any of the
+        ``set_state`` and ``get_state`` are not needed to work with any of the
         random distributions in NumPy. If the internal state is manually altered,
         the user should know exactly what he/she is doing.
 
@@ -559,7 +559,7 @@ cdef class RandomState:
 
         Results are from the "continuous uniform" distribution over the
         stated interval.  To sample :math:`Unif[a, b), b > a` multiply
-        the output of `random_sample` by `(b-a)` and add `a`::
+        the output of ``random_sample`` by `(b-a)` and add `a`::
 
           (b - a) * random_sample() + a
 

randomstate/shims/dSFMT/dSFMT.pxi

@@ -84,7 +84,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
+``dSFMT.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -105,7 +105,7 @@ Parameters
 seed : {None, int}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer in [0, 2**32] or ``None`` (the default).
-    If `seed` is ``None``, then `dSFMT.RandomState` will try to read
+    If `seed` is ``None``, then ``dSFMT.RandomState`` will try to read
     entropy from ``/dev/urandom`` (or the Windows analogue) if available to
     produce a 64-bit seed. If unavailable, the a 64-bit hash of the time
     and process ID is used.

randomstate/shims/mrg32k3a/mrg32k3a.pxi

@@ -55,7 +55,7 @@ MRG32K3A is a 32-bit implementation of L'Ecuyer's combined multiple
 recursive generator ([1]_, [2]_). MRG32K3A has a period of 2**191 and
 supports multiple streams (NOT IMPLEMENTED YET).
 
-`mrg32k3a.RandomState` exposes a number of methods for generating random
+``mrg32k3a.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -64,10 +64,10 @@ 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*
-'mrg32k3a.RandomState' does not make a guarantee that a fixed seed and a
-fixed series of calls to 'mrg32k3a.RandomState' methods using the same
+``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
-'numpy.random.RandomState' guarantee. This is done to simplify improving
+``numpy.random.RandomState`` guarantee. This is done to simplify improving
 random number generators.  To ensure identical results, you must use the
 same release version.
 
@@ -76,7 +76,7 @@ Parameters
 seed : {None, int}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer in [0, 2**64] or ``None`` (the default).
-    If `seed` is ``None``, then `mrg32k3a.RandomState` will try to read data
+    If `seed` is ``None``, then ``mrg32k3a.RandomState`` will try to read data
     from ``/dev/urandom`` (or the Windows analogue) if available or seed from
     the clock otherwise.
 

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

@@ -47,7 +47,7 @@ PCG-32 is a 64-bit implementation of O'Neill's permutation congruential
 generator ([1]_, [2]_). PCG-32 has a period of 2**64 and supports advancing 
 an arbitrary number of steps as well as 2**63 streams.
 
-`pcg32.RandomState` exposes a number of methods for generating random
+``pcg32.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -56,10 +56,10 @@ 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*
-'pcg32.RandomState' does not make a guarantee that a fixed seed and a
-fixed series of calls to 'pcg32.RandomState' methods using the same
+``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
-'numpy.random.RandomState' guarantee. This is done to simplify improving
+``numpy.random.RandomState`` guarantee. This is done to simplify improving
 random number generators.  To ensure identical results, you must use the
 same release version.
 
@@ -68,7 +68,7 @@ Parameters
 seed : {None, long}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer in [0, 2**64] or ``None`` (the default).
-    If `seed` is ``None``, then `xorshift1024.RandomState` will try to read data
+    If `seed` is ``None``, then ``pcg32.RandomState`` will try to read data
     from ``/dev/urandom`` (or the Windows analogue) if available or seed from
     the clock otherwise.  
 inc : {None, int}, optional

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

@@ -7,7 +7,7 @@ PCG-64 is a 128-bit implementation of O'Neill's permutation congruential
 generator ([1]_, [2]_). PCG-64 has a period of 2**128 and supports advancing
 an arbitrary number of steps as well as 2**127 streams.
 
-`pcg64.RandomState` exposes a number of methods for generating random
+``pcg64.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -16,10 +16,10 @@ 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*
-'pcg64.RandomState' does not make a guarantee that a fixed seed and a
-fixed series of calls to 'pcg64.RandomState' methods using the same
+``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
-'numpy.random.RandomState' guarantee. This is done to simplify improving
+``numpy.random.RandomState`` guarantee. This is done to simplify improving
 random number generators.  To ensure identical results, you must use the
 same release version.
 
@@ -28,7 +28,7 @@ Parameters
 seed : {None, long}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer in [0, 2**128] or ``None`` (the default).
-    If `seed` is ``None``, then `xorshift1024.RandomState` will try to read data
+    If `seed` is ``None``, then ``pcg64.RandomState`` will try to read data
     from ``/dev/urandom`` (or the Windows analogue) if available or seed from
     the clock otherwise.
 inc : {None, int}, optional

randomstate/shims/random-kit/random-kit.pxi

@@ -54,7 +54,7 @@ RandomState(seed=None)
 
 Container for the Mersenne Twister pseudo-random number generator.
 
-`mt19937.RandomState` exposes a number of methods for generating random
+``mt19937.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -63,9 +63,9 @@ array filled with generated values is returned. If `size` is a tuple,
 then an array with that shape is filled and returned.
 
 *Compatibility Guarantee*
-'mt19937.RandomState' is identical to 'numpy.random.RandomState' and
+``mt19937.RandomState`` is identical to ``numpy.random.RandomState`` and
 makes the same compatability guarantee. A fixed seed and a fixed series of
-calls to 'mt19937.RandomState' methods using the same parameters will always
+calls to ``mt19937.RandomState`` methods using the same parameters will always
 produce the same results up to roundoff error except when the values were
 incorrect. Incorrect values will be fixed and the version in which the fix
 was made will be noted in the relevant docstring. Extension of existing
@@ -78,15 +78,15 @@ seed : {None, int, array_like}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer, an array (or other sequence) of integers of
     any length, or ``None`` (the default).
-    If `seed` is ``None``, then `RandomState` will try to read data from
+    If `seed` is ``None``, then ``RandomState`` will try to read data from
     ``/dev/urandom`` (or the Windows analogue) if available or seed from
     the clock otherwise.
 
 Notes
 -----
 The Python stdlib module "random" also contains a Mersenne Twister
 pseudo-random number generator with a number of methods that are similar
-to the ones available in `RandomState`. `RandomState`, besides being
+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.
 """

randomstate/shims/xorshift1024/xorshift1024.pxi

@@ -58,7 +58,7 @@ generator [1]_. xorshift1024* has a period of 2**1024 - 1 and supports jumping
 the sequence in increments of 2**512, which allow multiple non-overlapping
 sequences to be generated.
 
-`xorshift1024.RandomState` exposes a number of methods for generating random
+``xorshift1024.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. 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
@@ -67,10 +67,10 @@ 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*
-'xorshift1024.RandomState' does not make a guarantee that a fixed seed and a
-fixed series of calls to 'xorshift1024.RandomState' methods using the same
+``xorshift1024.RandomState`` does not make a guarantee that a fixed seed and a
+fixed series of calls to ``xorshift1024.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
+``numpy.random.RandomState`` guarantee. This is done to simplify improving
 random number generators.  To ensure identical results, you must use the
 same release version.
 
@@ -79,7 +79,7 @@ Parameters
 seed : {None, int}, optional
     Random seed initializing the pseudo-random number generator.
     Can be an integer or ``None`` (the default).
-    If `seed` is ``None``, then `xorshift1024.RandomState` will try to read data
+    If `seed` is ``None``, then ``xorshift1024.RandomState`` will try to read data
     from ``/dev/urandom`` (or the Windows analogue) if available or seed from
     the clock otherwise.