some changes to the tutorials

doc/index.txt

@@ -10,7 +10,7 @@ arrays efficiently. Theano features:
 * **near-transparent use of a GPU** to accelerate for intense calculations [COMING].
 * **symbolic differentiation**
 * **speed and stability optimizations**: write ``log(1+exp(x))`` and get the right answer.
-* **dynamic C code generation** for faster evaluation
+* **dynamic C code generation** for faster expression evaluation
 
 Download
 ========
@@ -21,28 +21,24 @@ The current version is available via::
 
     hg clone http://hg.assembla.com/theano Theano
 
-The theano subfolder should be on your PYTHONPATH.  For more information about
+The theano subfolder should be on your ``$PYTHONPATH``.  For more information about
 installation and configuration, see :ref:`installing Theano <install>`.
 
 Documentation
 =============
 
 You can download the latest `PDF documentation <http://pylearn.org/theano/theano.pdf>`_, rather than reading it online.
-You can go to the :ref:`Table of Contents <contents>`.
-
-Shortcuts:
 
 * If you have no idea what Theano is read the :ref:`introduction <introduction>`.
 * :ref:`learn the basics <tutorial>`
 * :ref:`library reference <libdoc>`
-
-.. _contents:
-
-Full Documentation Table of Contents
-=====================================
+* :ref:`extending Theano <extending>` with new Types, and Ops
+* :ref:`internal docs <internal>`
+* :ref:`internal docs <internal>`
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    NEWS
    introduction
@@ -71,6 +67,7 @@ Community
 * Come visit us in Montreal!  Most of the developers are students in the LISA_ group at the `University of Montreal`_.
 
 
+
 .. _theano-dev: http://groups.google.com/group/theano-dev
 .. _theano-users: http://groups.google.com/group/theano-users
 .. _tickets: http://pylearn.org/theano/trac/query?status=accepted&status=assigned&status=new&status=reopened&group=milestone&max=200&col=id&col=summary&col=status&col=owner&col=type&col=priority&col=component&col=time&report=9&order=priority

doc/library/tensor/index.txt

@@ -98,6 +98,8 @@ Broadcasting in Theano vs. Numpy
 Random Sampling
 ===============
 
+See :ref:`libdoc_tensor_shared_randomstreams`.
+
 Linear Algebra
 ==============
 

doc/tutorial/index.txt

@@ -23,7 +23,6 @@ installation (see :ref:`install`).
     numpy
     adding
     examples
-    randomstreams
     debugmode
     profilemode
     debug_faq

doc/tutorial/randomstreams.txt

-.. _randomstreams:
-
-====================
-Using RandomStreams
-====================
-
-Since Theano uses a functional design, producing pseudo-random numbers in a
-graph is not quite as straightforward as it is in numpy.  But close.  If you are using theano's
-shared variables, then a RandomStreams object is probably what you want.  If you are
-using the function interface directly, or you are using Module then this tutorial will be useful but not exactly what you want.  
-Have a look at the :api:`RandomFunction` Op.
-
-The way to think about putting randomness into theano's computations is to
-put random variables in your graph.  Theano will allocate a numpy RandomState
-object for each such variable, and draw from it as necessary.  I'll call this sort of sequence of
-random numbers a *random stream*.
-
-Brief example
--------------
-
-Here's a brief example.  The setup code is:
-
-.. code-block:: python
-
-    from theano.tensor.shared_randomstreams import RandomStreams
-    srng = RandomStreams(seed=234)
-    rv_u = srng.uniform((2,2))
-    rv_n = srng.normal((2,2))
-    f = function([], rv_u, updates=[rv_u.update])
-    g = function([], rv_n)                              #omitting rv_n.update
-    nearly_zeros = function([], rv_u + rv_u - 2 * rv_u, updates=[rv_u.update])
-
-Here, 'rv_u' represents a random stream of 2x2 matrices of draws from a uniform
-distribution.  Likewise,  'rv_n' represenents a random stream of 2x2 matrices of
-draws from a normal distribution.  The distributions that are implemented are
-defined in :ref:`tensor.shared_randomstreams.RandomStreams`.
-
-Now let's use these things.  If we call f(), we get random uniform numbers.
-Since we are updating the internal state of the random number generator (via
-the ``updates`` argument, we get different random numbers every time.
-
->>> f_val0 = f()
->>> f_val1 = f()  #different numbers from f_val0
-
-When we omit the updates argument (as in ``g``) to ``function``, then the
-random number generator state is not affected by calling the returned function.  So for example, 
-calling ``g`` multiple times will return the same numbers.
-
->>> g_val0 = g()  # different numbers from f_val0 and f_val1
->>> g_val0 = g()  # same numbers as g_val0 !!!
-
-An important remark is that a random variable is drawn at most once during any
-single function execution.  So the ``nearly_zeros`` function is guaranteed to
-return approximately 0 (except for rounding error) even though the ``rv_u``
-random variable appears three times in the output expression.
-
->>> nearly_zeros = function([], rv_u + rv_u - 2 * rv_u, updates=[rv_u.update])
-
-
-Internal Attributes 
---------------------
-
-The random variables returned by methods like ``RandomStreams.uniform`` have
-some useful internal attributes.  
-
-The one we used above is the ``update`` attribute.  ``rv_u.update`` is a pair
-whose first element is a shared variable whose value is a numpy RandomState,
-and whose second element is an [symbolic] expression for the next value of that
-RandomState after drawing samples.
-
-The first element of the ``update`` attribute is also accessible as
-``rv_u.rng``.  A random variable can be re-seeded by seeding or assigning to
-``rv_u.rng.value``.
-
-The ``RandomStreams`` object itself has an ``updates()`` method that returns a
-list of all the (state, new_state) update pairs from the random variables it
-has returned.  This can be a convenient shortcut to enumerating all
-the random variables in a large graph in the ``update`` paramter of function.
-
-Seedings Streams
-----------------
-
-Random variables can be seeded individually or collectively.
-
-You can seed just one random variable by seeding or assigning to the
-``.rng.value`` attribute.
-
->>> rv_u.rng.value.seed(89234)  # seeds the generator for rv_u
-
-You can also seed *all* of the random variables allocated by a ``RandomStreams``
-object by that object's ``seed`` method.  This seed will be used to seed a
-temporary random number generator, that will in turn generate seeds for each
-of the random variables.
-
->>> srng.seed(902340)  # seeds rv_u and rv_n with different seeds each
-
-
-Sharing Streams between Functions
----------------------------------
-
-As usual for shared variables, the random number generators used for random
-variables are common between functions.  So our ``nearly_zeros`` function will
-update the state of the generators used in function ``f`` above.
-
-For example:
-
->>> state_after_v0 = rv_u.rng.value.get_state()
->>> nearly_zeros()       # this affects rv_u's generator
->>> v1 = f()             
->>> rv_u.rng.value.set_state(state_after_v0)
->>> v2 = f()             # v2 != v1
-
-
-.. _Tools: tools.html
-
-
-
-
-

doc/tutorial/tools.txt

@@ -170,8 +170,3 @@ bytes, we would do:
    my_cmatrix = theano.tensor.TensorType('complex64', [False, False])
 
 
-Ops
-===
-
-There are a lot of operations available in the :api:`theano.tensor` package.
-See :ref:`oplist`.

theano/tensor/raw_random.py

@@ -333,7 +333,7 @@ Note that the output will then be of dimension i+1.
 
 multinomial = random_function('multinomial', 'float64', 1, [0.5, 0.5], ndim_added=1)
 multinomial.__doc__ = """
-Usage: multinomial(random_state, size, n, pvals)
+Usage: multinomial(random_state, size, pvals)
 
 Sample from a multinomial distribution defined by probabilities pvals,
 as many times as required by size. For instance, if size=(p,q), p*q

theano/tensor/shared_randomstreams.py

@@ -126,6 +126,8 @@ class RandomStreams(object):
     def binomial(self, *args, **kwargs):
         """Return a symbolic binomial sample
 
+        *args and **kwargs will be passed to numpy.random.RandomState.binomial
+
         This is a shortcut for a call to `self.gen`
         """
         return self.gen(raw_random.binomial, *args, **kwargs)
@@ -133,6 +135,8 @@ class RandomStreams(object):
     def uniform(self, *args, **kwargs):
         """Return a symbolic uniform sample
 
+        *args and **kwargs will be passed to numpy.random.RandomState.uniform
+
         This is a shortcut for a call to `self.gen`
         """
         return self.gen(raw_random.uniform, *args, **kwargs)
@@ -140,6 +144,8 @@ class RandomStreams(object):
     def normal(self, *args, **kwargs):
         """Return a symbolic normal sample
 
+        *args and **kwargs will be passed to numpy.random.RandomState.normal
+
         This is a shortcut for a call to `self.gen`
         """
         return self.gen(raw_random.normal, *args, **kwargs)
@@ -147,6 +153,8 @@ class RandomStreams(object):
     def random_integers(self, *args, **kwargs):
         """Return a symbolic random integer sample
 
+        *args and **kwargs will be passed to numpy.random.RandomState.random_integers
+
         This is a shortcut for a call to `self.gen`
         """
         return self.gen(raw_random.random_integers, *args, **kwargs)