minor changes reading through the basic tutorial

doc/basic_tutorial/examples.txt

@@ -67,7 +67,7 @@ squared difference between two matrices ``x`` and ``y`` at the same time:
 >>> diff_squared = diff**2
 >>> f = function([x, y], [diff, abs_diff, diff_squared])
 
-When we use the function, it will return the two variables (the printing
+When we use the function, it will return the three variables (the printing
 was reformatted for readability):
 
 >>> f([[1, 1], [1, 1]], [[0, 1], [2, 3]])
@@ -141,7 +141,7 @@ with respect to the second. In this way, Theano can be used for
    first argument is a scalar or a tensor of size 1 but not if it is
    larger. For more information on the semantics when the first
    argument has a larger size and details about the implementation,
-   see the :ref:`gradient` section.
+   see :api:`tensor.grad`.
 
 
 Setting a default value for an argument
@@ -198,7 +198,7 @@ the increment has a default value of 1.
 First let's define the accumulator function:
 
 >>> inc = T.scalar('inc')
->>> state = T.scalar('state')
+>>> state = T.scalar('state_name')
 >>> new_state = state + inc
 >>> accumulator = function([(inc, 1), ((state, new_state), 0)], new_state)
 
@@ -212,8 +212,8 @@ of the internal ``state`` will be replaced by the value computed as
 ``new_state``. In this case, the state will be replaced by the variable
 of incrementing it by ``inc``.
 
-We recommend (insist?) that internal state arguments occur after any
-plain arguments and arguments with default values.
+.. We recommend (insist?) that internal state arguments occur after any plain
+   arguments and arguments with default values.
 
 There is no limit to how many states you can have. You can add an
 arbitrary number of elements to the input list which correspond to the
@@ -225,11 +225,11 @@ Anyway, let's try it out! The state can be accessed using the square
 brackets notation ``[]``. You may access the state either by using
 the :ref:`variable` representing it or the name of that
 :ref:`variable`. In our example we can access the state either with the
-``state`` object or the string 'state'.
+``state`` object or the string 'state_name'.
 
 >>> accumulator[state]
 array(0.0)
->>> accumulator['state']
+>>> accumulator['state_name']
 array(0.0)
 
 Here we use the accumulator and check that the state is correct each
@@ -237,21 +237,21 @@ time:
 
 >>> accumulator()
 array(1.0)
->>> accumulator['state']
+>>> accumulator['state_name']
 array(1.0)
 >>> accumulator(300)
 array(301.0)
->>> accumulator['state']
+>>> accumulator['state_name']
 array(301.0)
 
 It is possible to reset the state. This is done
 by assigning to the state using the square brackets
 notation:
 
->>> accumulator['state'] = 5
+>>> accumulator['state_name'] = 5
 >>> accumulator(0.9)
 array(5.9000000000000004)
->>> accumulator['state']
+>>> accumulator['state_name']
 array(5.9000000000000004)
 
 

doc/basic_tutorial/function.txt

@@ -12,7 +12,7 @@ The signature for this function is:
 
 .. code-block:: python
 
-    def function(inputs, outputs, mode='FAST_RUN'):
+    def function(inputs, outputs, mode=None):
         ...
 
 You've already seen example usage in the basic tutorial... something like this:
@@ -23,6 +23,8 @@ You've already seen example usage in the basic tutorial... something like this:
 
 The idea here is that we've compiled the symbolic graph (``2*x``) into a function that can be called on a number and will do some computations.
 
+.. _function_inputs:
+
 Inputs
 ======
 
@@ -278,6 +280,7 @@ In the example above, ``z`` has value 42 when no value is explicitly given.
 This default value is potentially used at every function invocation, because
 ``z`` has no ``update`` or storage associated with it.
 
+.. _function_outputs:
 
 Outputs
 =======
@@ -326,9 +329,10 @@ If a list of ``Variable`` or ``Out`` instances is given as argument, then the co
     print fn3(ndarray([[1,0],[0,1]]))
 
 
+.. _function_mode:
 
-Modes
-=====
+Mode
+====
 
 The ``mode`` parameter to ``theano.function`` controls how the
 inputs-to-outputs graph is transformed into a callable object.
@@ -341,6 +345,11 @@ Theano defines the following modes by name:
     implementations. This mode can take much longer than the other modes, 
     but can identify many kinds of problems.
 
+The default mode is typically 'FAST_RUN', but it can be controlled via the
+environment variable 'THEANO_DEFAULT_MODE', which can in turn be overridden by
+setting ``theano.compile.mode.default_mode`` directly, which can in turn be
+overridden by passing the keyword argument to ``theano.function``.
+
 For a finer level of control over which optimizations are applied, and whether
-C or python implementations are used, read :api:`theano.compile.Mode`.
+C or python implementations are used, read :api:`compile.mode.Mode`.
 

doc/basic_tutorial/randomstreams.txt

@@ -5,7 +5,7 @@ Using RandomStreams
 ====================
 
 Since Theano uses a functional design, producing pseudo-random numbers in a
-graph is almost as straightforward as it is in numpy.  If you are using theano's
+graph is not quite as straightforward as it is in numpy.  But close.  If you are using theano's
 modules, then a RandomStreams object is probably what you want.  If you are
 using the function interface directly (not Module and Method) then have a look
 at the :api:`RandomFunction` Op.
@@ -34,6 +34,7 @@ Here's a brief example:
     fn_val1 = made.fn()  #different numbers from fn_val0
 
 
+Let's walk through it.
 
 >>> from theano.tensor import RandomStreams
 >>> m = Module()
@@ -56,23 +57,23 @@ object for each of fn and gn).
 
 This function will always return a 2x2 matrix of small numbers, or possibly
 zeros.  It illustrates that random variables are not re-drawn every time they
-are used, they are only drawn once (per call).
+are used, they are only drawn once per method call.
 
 
 >>> made = m.make()
 
 When we compile things with m.make(), the RandomStreams instance (m.random)
-emits an RandomStreamsInstance object (made.random) containing a numpy
+emits an RandomStreamsInstance object (here called ``made.random``) containing a numpy
 RandomState instance for each stream.
 
 >>> assert isinstance(made.random[rv_u.rng], numpy.random.RandomState)
 
-These RandomState objects can be accessed using standard indexing syntax.
+These RandomState objects can be accessed using normal indexing syntax.
 
 >>> fn_val0 = made.fn()
 >>> fn_val1 = made.fn()
 
-Finally, we can use our toy methods to draw random numbers.  Every call will of
+Finally, we can use our methods to draw random numbers.  Every call will of
 course, draw different ones!
 
 
@@ -147,7 +148,7 @@ objects.  So, for example, if we were to hijack the previous example like this:
 >>> fn_val_ = made_again.fn()
 
 We could call f and g in different orders in the two modules, and find that
-numpy.all(fn_val == fn_val_) and numpy.all(gn_val == gn_val_).
+``numpy.all(fn_val == fn_val_)`` and ``numpy.all(gn_val == gn_val_)``.
 
 
 

doc/basic_tutorial/tools.txt

 
-=====
-Tools
-=====
+=============================
+Basic Tutorial Mini-Reference
+=============================
 
+.. miniref_mode:
 
 Mode
 ====
 
-WRITEME
+============= ==============================================================   ===============================================================================
+short name    Full constructor                                                 What does it do?
+============= ==============================================================   ===============================================================================
+-             ``compile.mode.Mode(linker='py', optimizer=None)``                Python implementations with zero graph modifications.
+FAST_COMPILE  ``compile.mode.Mode(linker='c|py', optimizer='fast_compile')      C implementations where available, quick and cheap graph transformations
+FAST_RUN      ``compile.mode.Mode(linker='c|py', optimizer='fast_run')          C implementations where available, all available graph transformations.
+DEBUG_MODE    ``compile.debugmode.DebugMode()                                   Both implementations where available, all available graph transformations.
+============= ==============================================================   ===============================================================================
 
 .. _tensortypes:
 
 Types
 =====
 
-NOTE: I'm not sure this actually goes in the tutorial - it ended up
-much longer than intended - maybe we should just link to it! --OB
-
 .. _predefinedtypes:
 
 Predefined types