docs: more work on random docs

doc/library/tensor/raw_random.txt

@@ -21,30 +21,16 @@ Reference
 
     A `Type` for variables that will take ``numpy.random.RandomState`` values.
 
+.. function:: random_state_type(name=None)
+
+    Return a new Variable whose ``.type`` is ``random_state_variable``.
+
 .. class:: RandomFunction(gof.Op)
 
     Op that draws random numbers from a numpy.RandomState object.  This Op is
     parametrized to draw numbers from many possible distributions.
 
-
-.. function:: random_function(fn, dtype, *rfargs, **rfkwargs)
-
-    Returns a wrapper around RandomFunction which automatically infers the number
-    of dimensions of the output from the given shape. If the shape cannot be inferred,
-    the user can give an integer as first argument, which will be interpreted as the
-    number of dimensions.
-
-    If the distribution is not scalar (e.g., a multinomial), the output will have
-    more dimensions than what the shape argument suggests. The "ndim_added" keyword
-    arguments allows to specify how many dimensions to add (for a multinomial, 1).
-
-    The number of dimensions for the following shape arguments can be inferred:
-
-    * shape(x)
-    * make_lvector(x, y, z, ...)
-    * ndarrays,  constants
-
-.. function:: uniform(random_state, size, low=0.0, high=1.0)
+.. function:: uniform(random_state, size=(), low=0.0, high=1.0)
 
     Sample from a uniform distribution between low and high.
 
@@ -54,7 +40,7 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: binomial(random_state, size, n=1, p=0.5)
+.. function:: binomial(random_state, size=(), n=1, p=0.5)
 
     Sample n times with probability of success prob for each trial,
     return the number of successes.
@@ -64,7 +50,7 @@ Reference
     to supplement the missing information.
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: normal(random_state, size, avg=0.0, std=1.0)
+.. function:: normal(random_state, size=(), avg=0.0, std=1.0)
 
     Sample from a normal distribution centered on avg with
     the specified standard deviation (std)
@@ -75,7 +61,7 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: random_integers(random_state, size, low=0, high=1)
+.. function:: random_integers(random_state, size=(), low=0, high=1)
 
     Sample a random integer between low and high, both inclusive.
 
@@ -85,7 +71,7 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: permutation(random_state, size, n=1)
+.. function:: permutation(random_state, size=(), n=1)
 
     Returns permutations of the integers between 0 and n-1, as many times
     as required by size. For instance, if size=(p,q), p*q permutations
@@ -98,7 +84,7 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: multinomial(random_state, size, p_vals=[0.5, 0.5])
+.. function:: multinomial(random_state, size=(), p_vals=[0.5, 0.5])
 
     Sample from a multinomial distribution defined by probabilities pvals,
     as many times as required by size. For instance, if size=(p,q), p*q
@@ -110,3 +96,72 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
+.. class:: RandomStreamsBase(object)
+
+    .. method:: binomial(self, size=(), n=1, prob=0.5, ndim=None):
+
+        Sample n times with probability of success prob for each trial, return the number of
+        successes.
+
+        If the size argument is ambiguous on the number of dimensions, the first argument may be a
+        plain integer to supplement the missing information.
+
+    .. method:: uniform(self,  size=(), low=0.0, high=1.0, ndim=None):
+
+        Sample a tensor of given size whose element from a uniform distribution between low and high.
+
+        If the size argument is ambiguous on the number of
+        dimensions, the first argument may be a plain integer
+        to supplement the missing information.
+
+    .. method:: normal(self, size=(), avg=0.0, std=1.0, ndim=None):
+
+        Usage: normal(random_state, size,
+        Sample from a normal distribution centered on avg with
+        the specified standard deviation (std)
+
+        If the size argument is ambiguous on the number of
+        dimensions, the first argument may be a plain integer
+        to supplement the missing information.
+
+    .. method:: random_integers(self, size=(), low=0, high=1, ndim=None):
+
+        Usage: random_integers(random_state, size, low=0, high=1)
+        Sample a random integer between low and high, both inclusive.
+
+        If the size argument is ambiguous on the number of
+        dimensions, the first argument may be a plain integer
+        to supplement the missing information.
+
+    .. method:: permutation(self, size=(), n=1, ndim=None):
+
+        Returns permutations of the integers between 0 and n-1, as many times
+        as required by size. For instance, if size=(p,q), p*q permutations
+        will be generated, and the output shape will be (p,q,n), because each
+        permutation is of size n.
+
+        Theano tries to infer the number of dimensions from the length of the size argument, but you
+        may always specify it with the `ndim` parameter.
+
+        .. note:: 
+            Note that the output will then be of dimension ndim+1.
+
+    .. method:: multinomial(self, size=(), n=1, pvals=[0.5, 0.5], ndim=None):
+
+        Sample n times from a multinomial distribution defined by probabilities pvals,
+        as many times as required by size. For instance, if size=(p,q), p*q
+        samples will be drawn, and the output shape will be (p,q,len(pvals)).
+
+        Theano tries to infer the number of dimensions from the length of the size argument, but you
+        may always specify it with the `ndim` parameter.
+
+        .. note:: 
+            Note that the output will then be of dimension ndim+1.
+
+    .. method:: shuffle_row_elements(self, input):
+        
+        Return a variable with every row (rightmost index) shuffled.
+        
+        This uses permutation random variable internally, available via the ``.permutation``
+        attribute of the return value.
+    

doc/library/tensor/shared_randomstreams.txt

@@ -101,10 +101,11 @@ For example:
 Reference
 =========
 
-.. class:: RandomStreams(object)
+.. class:: RandomStreams(raw_random.RandomStreamsBase)
 
-    This is a symbolic stand-in for ``numpy.random.RandomState``. It has
-    methods such as `uniform` and `normal` that return symbolic random variables.
+    This is a symbolic stand-in for ``numpy.random.RandomState``. 
+    Random variables of various distributions are instantiated by calls to
+    parent class :class:`raw_random.RandomStreamsBase`.
 
     .. method:: updates()
 
@@ -118,34 +119,22 @@ Reference
 
         `meta_seed` will be used to seed a temporary random number generator,
         that will in turn generate seeds for each of the random variables that
-        has been created by this object.
+        has been created by this object (via `gen`).
 
         :returns: None
 
-    .. method:: binomial(self, size, n=1, p=0.5)
+    .. method:: gen(op, *args, **kwargs)
 
-        Symbolic stand-in for numpy.random.RandomState.binomial
+        Return the random variable from `op(*args, **kwargs)`, but
+        also install special attributes (``.rng`` and ``update``, see
+        :class:`RandomVariable` ) into it.
 
-        :returns: :class:`RandomVariable` of float64 that will have `shape==size` at run-time.
+        This function also adds the returned variable to an internal list so
+        that it can be seeded later by a call to `seed`.
 
-    .. method:: uniform(self, size, low=0.0, high=1.0)
-
-        Symbolic stand-in for numpy.random.RandomState.uniform
-
-        :returns: :class:`RandomVariable` of float64 that will have `shape==size` at run-time.
-
-    .. method:: normal(self, size, loc=0.0, std=1.0)
-
-        Symbolic stand-in for numpy.random.RandomState.normal
-
-        :returns: :class:`RandomVariable` of float64 that will have `shape==size` at run-time.
-
-    .. method:: random_integers(self, size, low=0, high=1)
-
-        Symbolic stand-in for numpy.random.RandomState.random_integers
-
-        :returns: :class:`RandomVariable` of int64 that will have `shape==size` at run-time.
+    .. method:: uniform, normal, binomial, multinomial, random_integers, ...
 
+        See :class:`raw_random.RandomStreamsBase`.
 
 .. class:: RandomVariable(object)
 

theano/tensor/raw_random.py

@@ -236,7 +236,6 @@ def normal(random_state, size=(),  avg=0.0, std=1.0, ndim=None):
             tensor.TensorType(dtype = 'float64', broadcastable = (False,)*ndim) )
     return op(random_state, size, avg, std)
 
-
 def random_integers(random_state, size=(), low=0, high=1, ndim=None):
     """
     Usage: random_integers(random_state, size, low=0, high=1)
@@ -278,7 +277,6 @@ def permutation_helper(random_state, n, shape):
     print 'RETURNING', out.shape
     return out
 
-
 def permutation(random_state, size=(), n=1, ndim=None):
     """
     Returns permutations of the integers between 0 and n-1, as many times