numpydoc for theano/sandbox/rng_mrg.py

theano/sandbox/rng_mrg.py

 """
-Implementation of MRG31k3p random number generator for Theano
+Implementation of MRG31k3p random number generator for Theano.
 
-Generator code in SSJ package (L'Ecuyer & Simard)
+Generator code in SSJ package (L'Ecuyer & Simard).
 http://www.iro.umontreal.ca/~simardr/ssj/indexe.html
 
 """
@@ -39,11 +39,14 @@ def matVecModM(A, s, m):
 
 def multMatVect(v, A, m1, B, m2):
     """
-    multiply the first half of v by A with a modulo of m1
-    and the second half by B with a modulo of m2
+    Multiply the first half of v by A with a modulo of m1 and the second half
+    by B with a modulo of m2.
+
+    Notes
+    -----
+    The parameters of dot_modulo are passed implicitly because passing them
+    explicitly takes more time than running the function's C-code.
 
-    Note: The parameters of dot_modulo are passed implicitly because passing
-    them explicitly takes more time then running the function's C-code.
     """
     if multMatVect.dot_modulo is None:
         A_sym = tensor.lmatrix('A')
@@ -76,7 +79,8 @@ class DotModulo(Op):
     Efficient and numerically stable implementation of a dot product followed
     by a modulo operation. This performs the same function as matVecModM.
 
-    We do this 2 times on 2 triple inputs and concatenating the output
+    We do this 2 times on 2 triple inputs and concatenating the output.
+
     """
     __props__ = ()
 
@@ -1014,9 +1018,12 @@ def guess_n_streams(size, warn=False):
     """
     Return a guess at a good number of streams.
 
-    :param warn:
-      If True, warn when a guess cannot be made (in which case we
-      return 60 * 256).
+    Parameters
+    ----------
+    warn : bool, optional
+        If True, warn when a guess cannot be made (in which case we
+        return 60 * 256).
+
     """
     # TODO: a smart way of choosing the number of streams, see #612.
     # Note that this code was moved out of `MRG_RandomStreams` so that it can
@@ -1048,22 +1055,25 @@ def guess_n_streams(size, warn=False):
 
 
 class MRG_RandomStreams(object):
-    """Module component with similar interface to numpy.random (numpy.random.RandomState)"""
+    """
+    Module component with similar interface to numpy.random 
+    (numpy.random.RandomState).
+
+    Parameters
+    ----------
+    seed : int or list of 6 int
+        A default seed to initialize the random state.
+        If a single int is given, it will be replicated 6 times.
+        The first 3 values of the seed must all be less than M1 = 2147483647,
+        and not all 0; and the last 3 values must all be less than
+        M2 = 2147462579, and not all 0.
+
+    """
 
     def updates(self):
         return list(self.state_updates)
 
     def __init__(self, seed=12345, use_cuda=None):
-        """
-        :type seed: int or list of 6 int.
-
-        :param seed: a default seed to initialize the random state.
-            If a single int is given, it will be replicated 6 times.
-            The first 3 values of the seed must all be less than M1 = 2147483647,
-            and not all 0; and the last 3 values must all be less than
-            M2 = 2147462579, and not all 0.
-
-        """
         # A list of pairs of the form (input_r, output_r), representing the
         # update rules of all the random states generated by this RandomStreams.
         self.state_updates = []
@@ -1107,14 +1117,18 @@ class MRG_RandomStreams(object):
             raise TypeError("seed should be 1 integer or 6 integers")
 
     def seed(self, seed=None):
-        """Re-initialize each random stream
-
-        :param seed: each random stream will be assigned a unique
-        state that depends deterministically on this value.
+        """
+        Re-initialize each random stream.
 
-        :type seed: None or integer in range 0 to 2**30
+        Parameters
+        ----------
+        seed : None or integer in range 0 to 2**30
+            Each random stream will be assigned a unique state that depends
+            deterministically on this value.
 
-        :rtype: None
+        Returns
+        -------
+        None
 
         """
         if seed is None:
@@ -1133,14 +1147,20 @@ class MRG_RandomStreams(object):
             old_r.set_value(rstates, borrow=True)
 
     def inc_rstate(self):
-        """Update self.rstate to be skipped 2^134 steps forward to the next stream start"""
+        """
+        Update self.rstate to be skipped 2^134 steps forward to the next stream
+        start.
+
+        """
         #self.rstate = ff_2p134(self.rstate)
         self.rstate = multMatVect(self.rstate, A1p134, M1, A2p134, M2)
         assert self.rstate.dtype == numpy.int32
 
     def get_substream_rstates(self, n_streams, dtype, inc_rstate=True):
-        """Initialize a matrix in which each row is a MRG stream state,
+        """
+        Initialize a matrix in which each row is a MRG stream state,
         and they are spaced by 2**72 samples.
+
         """
         assert isinstance(dtype, str)
         assert n_streams < 2**72
@@ -1198,27 +1218,25 @@ class MRG_RandomStreams(object):
         distribution between low and high.
 
         If the size argument is ambiguous on the number of dimensions,
-        ndim may be a plain integer to supplement the missing
-        information.
-
-        :param low:
-          Lower bound of the interval on which values are sampled.  If
-          the ``dtype`` arg is provided, ``low`` will be cast into
-          dtype.  This bound is excluded.
-
-        :param high:
-          Higher bound of the interval on which values are sampled.
-          If the ``dtype`` arg is provided, ``high`` will be cast into
-          dtype.  This bound is excluded.
-
-        :param size:
+        ndim may be a plain integer to supplement the missing information.
+
+        Parameters
+        ----------
+        low
+            Lower bound of the interval on which values are sampled. 
+            If the ``dtype`` arg is provided, ``low`` will be cast into
+            dtype. This bound is excluded.
+        high
+            Higher bound of the interval on which values are sampled.
+            If the ``dtype`` arg is provided, ``high`` will be cast into
+            dtype. This bound is excluded.
+        size
           Can be a list of integer or Theano variable (ex: the shape
-          of other Theano Variable)
-
-        :param dtype:
-          The output data type. If dtype is not specified, it will be
-          inferred from the dtype of low and high, but will be at
-          least as precise as floatX.
+          of other Theano Variable).
+        dtype
+            The output data type. If dtype is not specified, it will be
+            inferred from the dtype of low and high, but will be at
+            least as precise as floatX.
 
         """
         low = as_tensor_variable(low)
@@ -1300,15 +1318,17 @@ class MRG_RandomStreams(object):
         Example : pvals = [[.98, .01, .01], [.01, .98, .01]] will
         probably result in [[1,0,0],[0,1,0]].
 
-        .. note::
-            -`size` and `ndim` are only there keep the same signature as other
-            uniform, binomial, normal, etc.
-            todo : adapt multinomial to take that into account
+        Notes
+        -----
+        -`size` and `ndim` are only there keep the same signature as other
+        uniform, binomial, normal, etc.
+        TODO : adapt multinomial to take that into account
+
+        -Does not do any value checking on pvals, i.e. there is no
+        check that the elements are non-negative, less than 1, or
+        sum to 1. passing pvals = [[-2., 2.]] will result in
+        sampling [[0, 0]]
 
-            -Does not do any value checking on pvals, i.e. there is no
-             check that the elements are non-negative, less than 1, or
-             sum to 1. passing pvals = [[-2., 2.]] will result in
-             sampling [[0, 0]]
         """
         if pvals is None:
             raise TypeError("You have to specify pvals")
@@ -1342,17 +1362,17 @@ class MRG_RandomStreams(object):
     def normal(self, size, avg=0.0, std=1.0, ndim=None,
                dtype=None, nstreams=None):
         """
-        :param size:
-          Can be a list of integers or Theano variables (ex: the shape
-          of another Theano Variable)
-
-        :param dtype:
-          The output data type. If dtype is not specified, it will be
-          inferred from the dtype of low and high, but will be at
-          least as precise as floatX.
-
-        :param nstreams:
-          Number of streams.
+        Parameters
+        ----------
+        size
+            Can be a list of integers or Theano variables (ex: the shape
+            of another Theano Variable).
+        dtype
+            The output data type. If dtype is not specified, it will be
+            inferred from the dtype of low and high, but will be at
+            least as precise as floatX.
+        nstreams
+            Number of streams.
 
         """
         # We need an even number of ]0,1[ samples. Then we split them