rewrote examples in basic tutorial to use In

doc/basic_tutorial/examples.txt

@@ -153,15 +153,16 @@ one. You can do it like this:
 
 >>> x, y = T.dscalars('x', 'y')
 >>> z = x + y
->>> f = function([x, (y, 1)], z)
+>>> f = function([x, In(y, value = 1)], z)
 >>> f(33)
 array(34.0)
 >>> f(33, 2)
 array(35.0)
 
-The syntax is that if one of the elements in the list of inputs is a
-pair, the input is the first element of the pair and the second
-element is its default value. Here ``y``'s default value is set to 1.
+This makes use of the :ref:`In <function_inputs>` class which allows
+you to specify properties of your inputs with greater detail. Here we
+give a default value of 1 for ``y`` by creating an In instance with
+its value field set to 1.
 
 Inputs with default values should (must?) follow inputs without default
 values.  There can be multiple inputs with default values. Defaults can
@@ -169,7 +170,7 @@ be set positionally or by name, as in standard Python:
 
 >>> x, y, w = T.dscalars('x', 'y', 'w')
 >>> z = (x + y) * w
->>> f = function([x, (y, 1), (w, 2)], z)
+>>> f = function([x, In(y, value = 1), In(w, value = 2)], z)
 >>> f(33)
 array(68.0)
 >>> f(33, 2)
@@ -180,8 +181,6 @@ array(33.0)
 array(34.0)
 >>> f(33, w=1, y=0)
 array(33.0)
->>> f(33, w=1, 2)
-<type 'exceptions.SyntaxError'>: non-keyword arg after keyword arg (<ipython console>, line 1)
 
 
 .. _functionstateexample:
@@ -200,26 +199,21 @@ First let's define the accumulator function:
 >>> inc = T.scalar('inc')
 >>> state = T.scalar('state_name')
 >>> new_state = state + inc
->>> accumulator = function([(inc, 1), ((state, new_state), 0)], new_state)
-
-The first argument is a pair. As we saw in the previous section, this
-means that ``inc`` is an input with a default value of 1. The second
-argument has syntax that creates an internal state.  The syntax is
-``((state_variable, new_state_variable), initial_value)``.
-The internal storage associated with ``state_variable`` is initialized to
-``initial_value``.  Every time ``accumulator`` is called, the value
-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``.
+>>> accumulator = function([In(inc, value = 1), In(state, value = 0, update = new_state)], new_state)
+
+The first argument, as seen in the previous section, defines a default
+value of 1 for ``inc``. The second argument adds another argument to
+In, ``update``, which works as follows: every time ``accumulator`` is
+called, the value of the internal ``state`` will be replaced by the
+value computed as ``new_state``. In this case, the state will be
+replaced by the result of incrementing it by ``inc``.
 
 .. 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
-syntax described in the previous paragraph. You can name the states
-however you like as long as the name does not conflict with the names
-of other inputs.
+There is no limit to how many states you can have and you can name
+them however you like as long as the name does not conflict with the
+names of other inputs.
 
 Anyway, let's try it out! The state can be accessed using the square
 brackets notation ``[]``. You may access the state either by using
@@ -255,5 +249,31 @@ array(5.9000000000000004)
 array(5.9000000000000004)
 
 
+Mode
+====
+
+The ``mode`` parameter to ``theano.function`` controls how the
+inputs-to-outputs graph is transformed into a callable object.
+
+Theano defines the following modes by name:
+
+- ``FAST_COMPILE``: Apply just a few optimizations, but use C op implementations where possible.
+- ``FAST_RUN``: Apply all optimizations, and use C op implementations where possible.
+- ``DEBUG_MODE``: Verify the correctness of all optimizations, and compare C and python 
+    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:`compile.mode.Mode`.
+
+
+
 .. _automatic differentiation: http://en.wikipedia.org/wiki/Automatic_differentiation
 

doc/topics/function.txt

@@ -31,47 +31,35 @@ Inputs
 The ``inputs`` argument to ``theano.function`` is a list, containing the ``Variable`` instances for which values will be specified at the time of the function call.  But inputs can be more than just Variables.  
 ``In`` instances let us attach properties to ``Variables`` to tell function more about how to use them.
 
-**In(variable, name=None, value=None, update=None, mutable=False)** returns an ``In`` instance:
 
-  - ``variable``: a Variable instance. 
+.. class:: In
 
-    This will be assigned a value before running the function,
-    not computed from its owner.
-  
-  - ``name``: Any type. (If autoname_input=True, defaults to variable.name). 
-
-    If name is a valid Python identifier, this input can be set by
-    ``kwarg``, and its value can be accessed by ``self.<name>``.
+   .. function:: __init__(variable, name=None, value=None, update=None, mutable=False)
 
-    Default: ``None``
+      ``variable``: a Variable instance. This will be assigned a value
+      before running the function, not computed from its owner.
+  
+      ``name``: Any type. (If autoname_input=True, defaults to
+      variable.name). If name is a valid Python identifier, this input
+      can be set by ``kwarg``, and its value can be accessed by
+      ``self.<name>``. The default value is ``None``
      
-  - ``value``: literal or Container
-
-    This is the default value of the Input.
-
-    Default: ``None``
-
-  - ``update``: Variable instance
-
-    This expression Variable will replace ``value`` after each function call.
-
-    Default: ``None``
-
-  - ``mutable``: Bool (requires value)
-
-    If ``True``, permit the compiled function to modify the python object being used as the default value.
-
-    Default: ``False``
+      ``value``: literal or Container. This is the default value of
+      the Input. The default value of this parameter is ``None``
 
-  - ``autoname``: Bool
+      ``update``: Variable instance. This expression Variable will
+      replace ``value`` after each function call. The default value is
+      ``None``, indicating that no update is to be done.
 
-    ``True``: if ``name`` is None and the Variable has a name, it will be taken
-    as the input's name.
+      ``mutable``: Bool (requires value). If ``True``, permit the
+      compiled function to modify the python object being used as the
+      default value. The default value is ``False``.
 
-    ``False``: the name is the exact value passed as the name parameter
-    (possibly ``None``).
+      ``autoname``: Bool. If set to ``True``, if ``name`` is None and
+      the Variable has a name, it will be taken as the input's
+      name. If autoname is set to ``False``, the name is the exact
+      value passed as the name parameter (possibly ``None``).
 
-    Default: ???
 
 Value: initial and default values
 ---------------------------------