merge

doc/advanced/function.txt

+
+.. _function:
+
+==================
+function interface
+==================
+
+WRITEME
+

doc/advanced/index.txt

 
 .. _advanced:
 
-===============
-Advanced Topics
-===============
+====================================
+Advanced Topics (under construction)
+====================================
 
 .. toctree::
     :maxdepth: 2
    
-    pipeline
-    unittest
-    profilemode
-    debug_faq
-    debugmode
-    module_vs_op
-    randomstreams
+    env
+    features
+    optimization
+    compilation
+    ccodegen
+    function
+    module
 
-
-.. env
-.. features
-.. optimization
-.. compilation
-.. ccodegen
-.. function
-.. module

doc/advanced_tutorial/constype.txt

-
-
-====================
-Making the cons type
-====================
-
-WRITEME

doc/advanced_tutorial/cop.txt

@@ -26,21 +26,23 @@ What needs to be defined
 
 There are less methods to define for an Op than for a Type:
 
-- **c_code(node, name, input_names, output_names, sub)**
+.. function:: c_code(node, name, input_names, output_names, sub)
 
-  - This must return C code that carries the computation we want to
-    do.
+  This must return C code that carries the computation we want to do.
 
-- **c_code_cleanup(node, name, input_names, output_names, sub)**
+.. function:: c_code_cleanup(node, name, input_names, output_names, sub)
 
-  - This must return C code that cleans up whatever c_code allocated
-    and that we must free.
+  This must return C code that cleans up whatever c_code allocated and
+  that we must free.
 
-  - *Default* The default behavior is to do nothing.
+  *Default* The default behavior is to do nothing.
 
-- **c_compile_args(), c_headers(), c_libraries(), c_support_code()**
+.. function:: c_compile_args()
+              c_headers()
+              c_libraries()
+              c_support_code()
 
-  - Allows you to specify headers, libraries, special g++ arguments or
+  Allows you to specify headers, libraries, special g++ arguments or
   helper functions/structs that the type needs. See :ref:`op`.
 
 

doc/advanced_tutorial/ctype.txt

@@ -46,37 +46,40 @@ be found in the documentation for :ref:`type`. Here, we'll focus on
 the most important ones:
 
 
-- **c_declare(name, sub)**
+.. function:: c_declare(name, sub)
 
-  - This must return C code which declares variables. These variables
+  This must return C code which declares variables. These variables
   will be available to operations defined in C. You may also write
   typedefs.
 
-- **c_init(name, sub)**
+.. function:: c_init(name, sub)
 
-  - This must return C code which initializes the variables declared
-    in c_declare. Either this or c_extract will be called.
+  This must return C code which initializes the variables declared in
+  c_declare. Either this or c_extract will be called.
 
-- **c_extract(name, sub)**
+.. function:: c_extract(name, sub)
 
-  - This must return C code which takes a reference to a Python object
+  This must return C code which takes a reference to a Python object
   and initializes the variables declared in c_declare to match the
   Python object's data. Either this or c_init will be called.
 
-- **c_sync(name, sub)**
+.. function:: c_sync(name, sub)
 
-  - When the computations are done, transfer the variables from the C
-    structure we put them in to the destination Python object. This
-    will only be called for the outputs.
+  When the computations are done, transfer the variables from the C
+  structure we put them in to the destination Python object. This will
+  only be called for the outputs.
 
-- **c_cleanup(name, sub)**
+.. function:: c_cleanup(name, sub)
 
-  - When we are done using the data, clean up whatever we allocated
-    and decrease the appropriate reference counts.
+  When we are done using the data, clean up whatever we allocated and
+  decrease the appropriate reference counts.
 
-- **c_compile_args(), c_headers(), c_libraries(), c_support_code()**
+.. function:: c_compile_args()
+              c_headers()
+              c_libraries()
+              c_support_code()
 
-  - Allows you to specify headers, libraries, special g++ arguments or
+  Allows you to specify headers, libraries, special g++ arguments or
   helper functions/structs that the type needs. See :ref:`type`.
 
 

doc/advanced_tutorial/index.txt

@@ -24,7 +24,7 @@ grounding for fundamental Theano concepts.
 
 .. toctree::
 
-   theano_vs_python
+   theano_vs_c
    graphstructures
    type
    op

doc/advanced_tutorial/optimization.txt

@@ -38,23 +38,23 @@ Global optimization
 A global optimization (or optimizer) is an object which defines the following
 methods:
 
-- **apply(env)**
+.. function:: apply(env)
 
-  - This method takes an Env object which contains the computation
-    graph and does modifications in line with what the optimization is
-    meant to do. This is of the main method of the optimizer.
+  This method takes an Env object which contains the computation graph
+  and does modifications in line with what the optimization is meant
+  to do. This is of the main method of the optimizer.
 
-- **add_requirements(env)**
+.. function:: add_requirements(env)
 
-  - This method takes an Env object and adds :ref:`features
+  This method takes an Env object and adds :ref:`features
   <envfeature>` to it. These features are "plugins" that are needed
   for the apply method to do its job properly.
 
-- **optimize(env)**
+.. function:: optimize(env)
 
-  - This is the interface function called by Theano.
+  This is the interface function called by Theano.
 
-  - *Default:* this is defined by Optimizer as ``add_requirement(env);
+  *Default:* this is defined by Optimizer as ``add_requirement(env);
   apply(env)``.
 
 See the section about :ref:`env` to understand how to define these
@@ -66,9 +66,9 @@ Local optimization
 
 A local optimization is an object which defines the following methods:
 
-- **transform(node)**
+.. function:: transform(node)
 
-  - This method takes an :ref:`apply` node and returns either False to
+  This method takes an :ref:`apply` node and returns either False to
   signify that no changes are to be done or a list of Variables which
   matches the length of the node's ``outputs`` list. When the
   LocalOptimizer is applied by a Navigator, the outputs of the node
@@ -380,21 +380,21 @@ A Query is built by the following call:
 
 theano.gof.Query(include, require = None, exclude = None, subquery = None)
 
-  * **include**: a set of tags (a tag being a string) such that every
-    optimization obtained through this Query must have **one** of the
-    tags listed. This field is required and basically acts as a
-    starting point for the search.
+**include**: a set of tags (a tag being a string) such that every
+optimization obtained through this Query must have **one** of the tags
+listed. This field is required and basically acts as a starting point
+for the search.
 
-  * **require**: a set of tags such that every optimization obtained
-    through this Query must have **all** of these tags.
+**require**: a set of tags such that every optimization obtained
+through this Query must have **all** of these tags.
 
-  * **exclude**: a set of tags such that every optimization obtained
-    through this Query must have **none** of these tags.
+**exclude**: a set of tags such that every optimization obtained
+through this Query must have **none** of these tags.
 
-  * **subquery**: optdb can contain sub-databases; subquery is a
-    dictionary mapping the name of a sub-database to a special Query.
-    If no subquery is given for a sub-database, the original Query
-    will be used again.
+**subquery**: optdb can contain sub-databases; subquery is a
+dictionary mapping the name of a sub-database to a special Query.  If
+no subquery is given for a sub-database, the original Query will be
+used again.
 
 Furthermore, a Query object includes three methods, ``including``,
 ``requiring`` and ``excluding`` which each produce a new Query object
@@ -454,8 +454,8 @@ Theano defines two EquilibriumDBs where you can put local
 optimizations:
 
 
-* **canonicalize**: this contains optimizations that aim to *simplify*
-  the graph:
+**canonicalize**: this contains optimizations that aim to *simplify*
+the graph:
 
   * Replace rare or esoterical operations with their equivalents using
     elementary operations.
@@ -467,8 +467,8 @@ optimizations:
   * Fold constants (Constant(2)*Constant(2) becomes Constant(4))
 
 
-* **specialize**: this contains optimizations that aim to *specialize*
-  the graph:
+**specialize**: this contains optimizations that aim to *specialize*
+the graph:
 
   * Replace a combination of operations with a special operation that
     does the same thing (but better).

doc/advanced_tutorial/theano_vs_python.txt → doc/advanced_tutorial/theano_vs_c.txt

 
-.. _theano_vs_python:
+.. _theano_vs_c:
 
-======================
-Theano vs. Python
-======================
+============
+Theano vs. C
+============
 
 We describe some of the patterns in Theano, and present their closest
-analogue in Python:
+analogue in a statically typed language such as C:
 
 =============== ===========================================================
-Theano          Python
+Theano          C
 =============== ===========================================================
 Apply           function application / function call
 Variable          function data / variable
@@ -17,3 +17,25 @@ Op              operations carried out in computation / function definition
 Type            data types
 Module          ??? class?
 =============== ===========================================================
+
+For example:
+
+.. code-block:: c
+
+   int main(int a) {
+       int b = 3;
+       int c = f(b)
+       return g(a, c);
+   }
+
+
+Based on this code snippet, we can relate f and g to Ops, a, b and c
+to Variables, g(a, c) and f(b) (taken as meaning the action of
+computing f or g on their respective inputs) to Applies. Lastly, int
+could be interpreted as the Theano Type of the Variables a and b.
+
+
+
+
+
+

doc/advanced_tutorial/type.txt

@@ -22,9 +22,9 @@ i.e.  the same default argument names and values. If you wish to add
 extra arguments to any of these methods, these extra arguments must have
 default values.
 
-- **filter(value, strict=False)**
+.. function:: filter(value, strict=False)
 
-  - This casts a value to match the Type and returns the
+  This casts a value to match the Type and returns the
   casted value. If ``value`` is incompatible with the Type,
   the method must raise an exception. If ``strict`` is True, ``filter`` must return a
   reference to ``value`` (i.e. casting prohibited)
@@ -33,58 +33,58 @@ default values.
   must be called ``strict`` (Theano often calls it by keyword) and must
   have a default value of ``False``.
 
-- **is_valid_value(value)**
+.. function:: is_valid_value(value)
 
-  - Returns True iff the value is compatible with the Type. If
+  Returns True iff the value is compatible with the Type. If
   ``filter(value, strict = True)`` does not raise an exception, the
   value is compatible with the Type.
 
-  - *Default*: True iff ``filter(value, strict = True)`` does not raise an
-    exception.
+  *Default*: True iff ``filter(value, strict = True)`` does not raise
+  an exception.
 
-- **values_eq(a, b)**
+.. function:: values_eq(a, b)
 
-  - Returns True iff ``a`` and ``b`` are equal.
+  Returns True iff ``a`` and ``b`` are equal.
 
-  - *Default*: ``a == b``
+  *Default*: ``a == b``
 
-- **values_eq_approx(a, b)**
+.. function:: values_eq_approx(a, b)
 
-  - Returns True iff ``a`` and ``b``
-    are approximately equal, for a definition of "approximately" which
-    varies from Type to Type.
+  Returns True iff ``a`` and ``b`` are approximately equal, for a
+  definition of "approximately" which varies from Type to Type.
 
-  - *Default*: ``values_eq(a, b)``
+  *Default*: ``values_eq(a, b)``
 
-- **make_variable(name=None)**
+.. function:: make_variable(name=None)
 
-  - Makes a :term:`Variable` of this Type with the specified name, if
+  Makes a :term:`Variable` of this Type with the specified name, if
   ``name is not None``. If ``name is ``None``, then the Variable does
-    not have a name. The Variable will have its ``type`` field set to the
-    Type object.
+  not have a name. The Variable will have its ``type`` field set to
+  the Type object.
 
-  - *Default*: there is a generic definition of this in Type. The Variable's
-    ``type`` will be the object that defines this method (in other words,
-    ``self``).
+  *Default*: there is a generic definition of this in Type. The
+  Variable's ``type`` will be the object that defines this method (in
+  other words, ``self``).
 
-- **__call__(name=None)**:
+.. function:: __call__(name=None)
 
-  - Syntactic shortcut to ``make_variable``.
+  Syntactic shortcut to ``make_variable``.
 
-  - *Default*: ``make_variable``
+  *Default*: ``make_variable``
 
-- **__eq__(self, other)**:
+.. function:: __eq__(other)
 
-  - Used to compare Type instances themselves
+  Used to compare Type instances themselves
 
-  - *Default*: ``object.__eq__``
+  *Default*: ``object.__eq__``
 
-- **__hash__(self)**:
+.. function:: __hash__()
 
-  - Types should not be mutable, so it should be Ok to define a hash function.
-    Typically this function should hash all of the terms involved in ``__eq__``.
+  Types should not be mutable, so it should be Ok to define a hash
+  function.  Typically this function should hash all of the terms
+  involved in ``__eq__``.
 
-  - *Default*: ``id(self)``
+  *Default*: ``id(self)``
 
 For each method, the *default* is what ``Type`` defines
 for you. So, if you create an instance of ``Type`` or an

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/basic_tutorial/index.txt

@@ -30,6 +30,5 @@ Now we're ready for the tour:
 
    adding
    examples
-   function
    module
    tools

doc/contents.txt

@@ -8,12 +8,13 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   LICENSE
+   index
    introduction
+   LICENSE
    install
-   numpy
    basic_tutorial/index
    advanced_tutorial/index
+   topics/index
    advanced/index
    indexes/index
    glossary

doc/install.txt

@@ -144,9 +144,9 @@ Generating the documentation
 ----------------------------
 
 You can read the latest HTML documentation `here
-<http://pylearn.org/theano/contents.html>`_.
+<http://pylearn.org/theano/contents.html>`__.
 You can download the latest PDF documentation `here
-<http://pylearn.org/theano/theano.pdf`_.
+<http://pylearn.org/theano/theano.pdf`__.
 
 We recommend you look at the documentation on the website, since it
 will be more current than the documentation included with the package.

doc/introduction.txt

@@ -6,30 +6,32 @@ Introduction
 ============
 
 Theano is a Python library that allows you to define, optimize, and
-efficiently evaluate mathematical expressions involving multi-dimensional
-arrays. Using Theano, it is not uncommon to see speed improvements of
-ten-fold over using pure NumPy.
+efficiently evaluate mathematical expressions involving
+multi-dimensional arrays. Using Theano, for problems involving large
+amounts of data, it is possible to attain speeds that are only a few
+percentage points slower than hand-crafted C implementations.
 
 Theano melds some aspects of a computer algebra system (CAS) with
-aspects of an optimizing compiler. It can even transform some or
-all of the mathematical expression into C code and compile it into
-native machine instructions. This combination of CAS with optimizing
-compilation is particularly useful for computational fields in which
-complicated mathematical expressions are evaluated repeatedly and evaluation
-speed is critical.
+aspects of an optimizing compiler. It can even transform some or all
+of the mathematical expression into C code and compile it into native
+machine instructions. This combination of CAS with optimizing
+compilation is particularly useful for tasks in which complicated
+mathematical expressions are evaluated repeatedly and evaluation speed
+is critical.
 
 Theano supports a range of numerical types in multiple dimensions and
 a number of well-tested operations. It also allows you to compute the
-gradient of an expression with respect to another. Symbolic expressions
-may be compiled into functions, which work on the same data structures
-as numpy_, allowing for easy interoperability.
+gradient of an expression with respect to another. Symbolic
+expressions may be compiled into functions, which work on the same
+data structures as numpy_, allowing for easy interoperability.
 
-Theano's compiler applies many optimizations of varying complexity
-to these symbolic expressions. These optimizations include, but are
-not limited to:
+Theano's compiler applies many optimizations of varying complexity to
+these symbolic expressions. These optimizations include, but are not
+limited to:
 
 * constant folding
-* merging of similar subgraphs, to avoid calculating the same values more than once
+* merging of similar subgraphs, to avoid calculating the same values
+  more than once
 * arithmetic simplification (``x*y/x -> y``)
 * inserting efficient BLAS_ operations
 * using inplace operations wherever it is safe to do so.
@@ -37,20 +39,18 @@ not limited to:
 Theano defines several optimizations which improve the numerical
 stability of computations.
 
-Theano was written at the LISA_ lab to support the development
-of efficient machine learning algorithms while minimizing human time. We
-use it especially in gradient-based learning techniques.
-Theano is named after the `Greek mathematician`_, who may have
-been Pythagoras' wife.
-Theano is released under a BSD license (:ref:`link <license>`)
+Theano was written at the LISA_ lab to support the development of
+efficient machine learning algorithms while minimizing human time. We
+use it especially in gradient-based learning techniques.  Theano is
+named after the `Greek mathematician`_, who may have been Pythagoras'
+wife.  Theano is released under a BSD license (:ref:`link <license>`)
 
 
 Sneak peek
 ==========
 
-Here is an example of how to use Theano. It doesn't show
-off many of Theano's features, but it illustrates concretely what
-Theano is.
+Here is an example of how to use Theano. It doesn't show off many of
+Theano's features, but it illustrates concretely what Theano is.
 
 .. code-block:: python
 
@@ -73,8 +73,8 @@ Theano is.
 
 
 Theano is not a programming language in the normal sense because you
-write a program in Python that builds expressions for Theano. Still
-it is like a programming language in the sense that you have to
+write a program in Python that builds expressions for Theano. Still it
+is like a programming language in the sense that you have to
 
 - declare variables (``a,b``) and give their types
 
@@ -119,7 +119,6 @@ Theano is a sort of hybrid of the two which tries to make the best of
 both worlds.
 
 
-
 Getting started
 ===============
 
@@ -152,8 +151,8 @@ Questions, comments, praise, criticism as well as bug reports should
 be submitted to these mailing lists.
 
 We welcome all kinds of contributions. If you have any questions
-regarding how to extend Theano, please feel free to ask on the theano-dev_
-mailing list.
+regarding how to extend Theano, please feel free to ask on the
+theano-dev_ mailing list.
 
 
 

doc/advanced/debug_faq.txt → doc/topics/debug_faq.txt

@@ -56,8 +56,9 @@ something that you're not seeing.
 I wrote a new optimization, but it's not getting used...
 ---------------------------------------------------------
 
-Remember that you have to register optimizations with the OptDb, for them to get
-used by the normal modes like FAST_COMPILE, FAST_RUN, and DEBUG_MODE.
+Remember that you have to register optimizations with the :ref:`optdb`
+for them to get used by the normal modes like FAST_COMPILE, FAST_RUN,
+and DEBUG_MODE.
 
 
 I wrote a new optimization, and it changed my results even though I'm pretty sure it is correct.
@@ -71,11 +72,13 @@ something that you're not seeing.
 The function I compiled is too slow, what's up?
 -----------------------------------------------
 
-First, make sure you're running in FAST_RUN mode, by passing ``mode='FAST_RUN'``
-to ``theano.function`` or ``theano.make``.
+First, make sure you're running in FAST_RUN mode, by passing
+``mode='FAST_RUN'`` to ``theano.function`` or ``theano.make``. Some
+operations have excruciatingly slow Python implementations and that
+can negatively effect the performance of FAST_COMPILE.
 
-Second, try the theano :ref:`profilemode`.  This will tell you which Apply nodes,
-and which Ops are eating up your CPU cycles.
+Second, try the theano :ref:`profilemode`.  This will tell you which
+Apply nodes, and which Ops are eating up your CPU cycles.
 
 
 .. _faq_wraplinker:

doc/advanced/debugmode.txt → doc/topics/debugmode.txt

@@ -41,6 +41,7 @@ In the example above, there is no way to guarantee that a future call to say,
 
 There following are DebugMode exceptions you might encounter:
 
+
 BadCLinkerOutput
 ----------------
 
@@ -116,6 +117,7 @@ performed, but the plan is that it will be.  (see ticket #320)
 
 For detailed documentation see :api:`FloatError`.
 
+
 InvalidValueError
 -----------------
 
@@ -126,6 +128,7 @@ Type.
 
 For detailed documentation see :api:`InvalidValueError`.
 
+
 DebugModeError
 --------------
 

doc/basic_tutorial/function.txt → doc/topics/function.txt

 
-.. _function:
+.. _usingfunction:
 
-===============
-theano.function
-===============
+=====================
+Using theano.function
+=====================
 
 
 This page is about ``theano.function``, the interface for compiling graphs into callable objects.
@@ -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.
+   .. function:: __init__(variable, name=None, value=None, update=None, mutable=False)
 
-  - ``name``: Any type. (If autoname_input=True, defaults to variable.name). 
+      ``variable``: a Variable instance. This will be assigned a value
+      before running the function, not computed from its owner.
   
-    If name is a valid Python identifier, this input can be set by
-    ``kwarg``, and its value can be accessed by ``self.<name>``.
+      ``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``
      
-    Default: ``None``
+      ``value``: literal or Container. This is the default value of
+      the Input. The default value of this parameter is ``None``
 
-  - ``value``: literal or Container
+      ``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.
 
-    This is the default value of the Input.
+      ``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``.
 
-    Default: ``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``).
 
-  - ``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``
-
-  - ``autoname``: Bool
-
-    ``True``: if ``name`` is None and the Variable has a name, it will be taken
-    as the input's name.
-
-    ``False``: the name is the exact value passed as the name parameter
-    (possibly ``None``).
-
-    Default: ???
 
 Value: initial and default values
 ---------------------------------

doc/topics/index.txt

+
+.. _topics:
+
+======
+Topics
+======
+
+.. toctree::
+    :maxdepth: 2
+   
+    function
+    pipeline
+    unittest
+    profilemode
+    debugmode
+    debug_faq
+    randomstreams
+

doc/advanced/profilemode.txt → doc/topics/profilemode.txt

@@ -17,20 +17,31 @@ First create a ProfileMode instance.
 >>> from theano import ProfileMode
 >>> profmode = theano.ProfileMode(optimizer='fast_run', linker=theano.gof.OpWiseCLinker())
 
-The ProfileMode constructor takes as input an optimizer and a linker. Which optimizer 
-and linker to use will depend on the application. For example, a user wanting
-to profile the Python implementation only, should use the gof.PerformLinker (or
-"py" for short). On the other hand, a user wanting to profile his graph using
-c-implementations wherever possible should use the ``gof.OpWiseCLinker`` (or "c|py").
+The ProfileMode constructor takes as input an optimizer and a
+linker. Which optimizer and linker to use will depend on the
+application. For example, a user wanting to profile the Python
+implementation only, should use the gof.PerformLinker (or "py" for
+short). On the other hand, a user wanting to profile his graph using C
+implementations wherever possible should use the ``gof.OpWiseCLinker``
+(or "c|py").
 
 In the same manner, modifying which optimizer is passed to ProfileMode
 will decide which optimizations are applied to the graph, prior to
-profiling. Changing the optimizer should be especially useful when developing
-new graph optimizations, in order to evaluate their impact on performance.
-
-Note that most users will want to use ProfileMode to optimize their graph and
-find where most of the computation time is being spent. In this context,
-'fast_run' optimizer and ``gof.OpWiseCLinker`` are the most appropriate choices.
+profiling. Changing the optimizer should be especially useful when
+developing new graph optimizations, in order to evaluate their impact
+on performance. Also keep in mind that optimizations might change the
+computation graph a lot, meaning that you might not recognize some of
+the operations that are profiled (you did not use them explicitly but
+an optimizer decided to use it to improve performance or numerical
+stability). If you cannot easily relate the output of ProfileMode with
+the computations you defined, you might want to try setting optimizer
+to None (but keep in mind the computations will be slower than if they
+were optimized).
+
+Note that most users will want to use ProfileMode to optimize their
+graph and find where most of the computation time is being spent. In
+this context, 'fast_run' optimizer and ``gof.OpWiseCLinker`` are the
+most appropriate choices.
 
 Compiling your Graph with ProfileMode
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -107,16 +118,20 @@ generates the following output:
     """
 
 
-The summary has two components to it. In the first section called the Apply-wise 
-summary, timing information is provided for the worst offending Apply nodes. This 
-corresponds to individual nodes within your graph which take the longest to
-execute. In the second portion, the Op-wise summary, the execution time of 
-all Apply nodes executing the same Op are grouped together and the total
-execution time per Op is shown.
+The summary has two components to it. In the first section called the
+Apply-wise summary, timing information is provided for the worst
+offending Apply nodes. This corresponds to individual Op applications
+within your graph which take the longest to execute (so if you use
+``dot`` twice, you will see two entries there). In the second portion,
+the Op-wise summary, the execution time of all Apply nodes executing
+the same Op are grouped together and the total execution time per Op
+is shown (so if you use ``dot`` twice, you will see only one entry
+there corresponding to the sum of the time spent in each of them).
 
-Note that the ProfileMode also shows which Ops were running a c implementation.
+Note that the ProfileMode also shows which Ops were running a c
+implementation.
 
-Developers wishing to optimize the performance of their graph, should focus on the 
-worst offending Ops. If no c-implementation exists for this op, consider writing
-a c-implementation yourself or use the mailing list, to suggest that a c-implementation
-be provided.
+Developers wishing to optimize the performance of their graph, should
+focus on the worst offending Ops. If no C implementation exists for
+this op, consider writing a C implementation yourself or use the
+mailing list, to suggest that a C implementation be provided.