merge

LICENSE.txt

-doc/doc/LICENSE.txt
\ No newline at end of file
+doc/LICENSE.txt
\ No newline at end of file

doc/advanced/compilation.txt

+
+.. _compilation:
+
+=======================
+Compilation and Linking
+=======================

doc/advanced/env.txt

+
+.. _env:
+
+===
+Env
+===

doc/advanced/function.txt

+
+.. _functioninterface:
+
+==================
+Function Interface
+==================
+
+This section details the various structures used to make ``function``
+work. You might want to read the sections about :ref:`compilation` and
+:ref:`optimization`.
+
+
+
+
+
+.. index::
+   single: Mode
+
+.. _mode:
+
+----
+Mode
+----
+
+WRITEME
+
+
+.. index::
+   single: function
+
+.. _function:
+
+--------
+function
+--------
+
+WRITEME
+
+
+.. index::
+   single: FunctionMaker
+
+.. _functionmaker:
+
+-------------
+FunctionMaker
+-------------
+
+WRITEME
+

doc/advanced/graphstructures.txt

+
+.. _graphstructures:
+
+================
+Graph Structures
+================
+
+Theano represents mathematical computations as graphs. These graphs
+are formed of interconnected :ref:`apply` and :ref:`result` nodes,
+which are standard types of objects. They are respectively associated
+to *function application* and *data*.  Two additional structures are
+used by Theano in order to represent the operations carried in the
+computations and the data types that are processed. Operations are
+represented :ref:`op` instances and data types are represented by
+:ref:`type` instances. Here is a piece of code and a diagram showing
+the structure built by that piece of code. This should help you
+understand how all these things play together:
+
+
+-----------------------
+
+**Code**
+
+.. code-block:: python
+
+    x = dmatrix('x')
+    y = dmatrix('y')
+    z = x + y
+
+**Diagram**
+
+.. image:: apply.png 
+
+-----------------------
+
+Arrows represent references to the Python objects pointed at. The blue
+box is an :ref:`apply` node. Red boxes are :ref:`result` nodes. Green
+circles are :ref:`Ops <op>`. Purple boxes are :ref:`Types <type>`.
+
+When we create :ref:`Results <result>` and then :ref:`apply`
+:ref:`operations <op>` to them to make more Results, we build a
+bi-partite, directed, acyclic graph. Results point to the Apply nodes
+representing the function application producing them via their
+``owner`` field. These Apply nodes point in turn to their input and
+output Results via their ``inputs`` and ``outputs`` fields.
+
+The ``owner`` field of both ``x`` and ``y`` point to ``None`` because
+they are not the result of another computation. If they were the
+result of another computation, they would point to another blue box
+like ``z`` does, and so on.
+
+
+An explicit example
+===================
+
+In this example we will see in turn a short example where the graph
+construction is hidden behind the standard interface's syntactic
+shortcuts and then the same example but rolled out so that the graph
+construction is made explicit.
+
+
+**Short example**
+
+This is what you would normally type:
+
+.. code-block:: python
+
+    from theano.tensor import *
+            
+    # create 3 Results with owner = None
+    x = matrix('x')
+    y = matrix('y')
+    z = matrix('z')
+    
+    # create 2 Results (one for 'e', one intermediate for y*z)
+    # create 2 Apply instances (one for '+', one for '*')
+    e = x + y * z
+
+
+**Long example**
+
+This is what you would type to build the graph explicitly:
+
+.. code-block:: python
+
+    from theano.tensor import *
+    
+    # We instantiate a type that represents a matrix of doubles
+    float64_matrix = Tensor(dtype = 'float64',              # double
+                            broadcastable = (False, False)) # matrix
+    
+    # We make the Result instances we need.
+    x = Result(type = float64_matrix, name = 'x')
+    y = Result(type = float64_matrix, name = 'y')
+    z = Result(type = float64_matrix, name = 'z')
+    
+    # This is the Result that we want to symbolically represents y*z
+    mul_result = Result(type = float64_matrix)
+    assert mul_result.owner is None
+    
+    # We instantiate a symbolic multiplication
+    node_mul = Apply(op = mul,
+                     inputs = [y, z],
+                     outputs = [mul_result])
+    assert mul_result.owner is node_mul and mul_result.index == 0 # these fields are set by Apply
+    
+    # This is the Result that we want to symbolically represents x+(y*z)
+    add_result = Result(type = float64_matrix)
+    assert add_result.owner is None
+    
+    # We instantiate a symbolic addition
+    node_add = Apply(op = add,
+                     inputs = [x, mul_result],
+                     outputs = [add_result])
+    assert add_result.owner is node_add and add_result.index == 0 # these fields are set by Apply
+    
+    e = add_result
+    
+    # We have access to x, y and z through pointers
+    assert e.owner.inputs[0] is x
+    assert e.owner.inputs[1] is mul_result
+    assert e.owner.inputs[1].owner.inputs[0] is y
+    assert e.owner.inputs[1].owner.inputs[1] is z
+
+
+Note how the call to ``Apply`` modifies the ``owner`` and ``index``
+fields of the :ref:`Results <result>` passed as outputs to point to
+itself and the rank they occupy in the output list. This whole
+machinery builds a DAG (Directed Acyclic Graph) representing the
+computation, a graph that theano can compile and optimize.
+
+
+Graph Structures
+================
+
+The following section outlines each type of structure that may be used
+in a Theano-built computation graph. The following structures are
+explained: :ref:`apply`, :ref:`constant`, :ref:`op`, :ref:`result` and
+:ref:`type`.
+
+
+.. index::
+   single: Apply
+   single: graph construct; Apply
+
+.. _apply:
+
+-----
+Apply
+-----
+
+An *Apply node* is a type of internal node used to represent a
+:term:`computation graph <graph>` in Theano. Unlike
+:ref:`Result nodes <result>`, Apply nodes are usually not
+manipulated directly by the end user. They may be accessed via
+a Result's ``owner`` field.
+
+An Apply node is typically an instance of the :api:`Apply
+<theano.gof.graph.Apply>` class. It represents the application
+of an :ref:`op` on one or more inputs, where each input is a
+:ref:`result`. By convention, each Op is responsible for
+knowing how to build an Apply node from a list of
+inputs. Therefore, an Apply node may be obtained from an Op
+and a list of inputs by calling ``Op.make_node(*inputs)``.
+
+Comparing with the Python language, an :ref:`apply` node is
+theano's version of a function call whereas an :ref:`op` is
+theano's version of a function definition.
+
+An Apply instance has three important fields:
+
+**inputs**
+  A list of :ref:`Results <result>` that represent the arguments of
+  the function.
+
+**outputs**
+  A list of :ref:`Results <result>` that represent the return values
+  of the function.
+
+**op**
+  An :ref:`op` that determines the function/transformation being
+  applied here.
+
+
+.. index::
+   single: Constant
+   single: graph construct; Constant
+
+.. _constant:
+
+--------
+Constant
+--------
+
+A constant is a :ref:`Result` with one extra field, *data* (only
+settable once). When used in a computation graph as the input of an
+:ref:`Op` :ref:`application <Apply>`, it is assumed that said input
+will *always* take the value contained in the constant's data
+field. Furthermore, it is assumed that the :ref:`Op` will not under
+any circumstances modify the input. This means that a constant is
+eligible to participate in numerous optimizations: constant inlining
+in C code, constant folding, etc.
+
+A constant does not need to be specified in a :ref:`function`'s list
+of inputs.
+
+
+
+.. index::
+   single: Result
+   single: graph construct; Result
+
+.. _result:
+
+------
+Result
+------
+
+A :ref:`result` is the main data structure you work with when using
+Theano. The symbolic inputs that you operate on are Results and what
+you get from applying various operations to these inputs are also
+Results. For example, when I type
+
+>>> x = theano.tensor.ivector()
+>>> y = -x
+
+``x`` and ``y`` are both Results, i.e. instances of the :api:`Result
+<theano.gof.graph.Result>` class. The :ref:`type` of both ``x`` and
+``y`` is ``theano.tensor.ivector``.
+
+Despite what the name might suggest, a Result is not necessarily
+produced by a computation. Indeed, in the example above, ``x`` is only
+an input. However, it is still called a Result for historical reasons
+(and because the data structure is identical).
+
+Now, unlike ``x``, ``y`` is indeed produced by a computation (in this
+case, negation of x). ``y`` is the Result corresponding to the output
+of the computation, while ``x`` is the Result corresponding to its
+input. The computation itself is represented by another type of node,
+an :ref:`apply` node, and may be accessed through ``y.owner``.
+
+More specifically, a Result is a basic structure in Theano that
+represents a datum at a certain point in computation. It is typically
+an instance of the class :api:`Result <theano.gof.graph.Result>` or
+one of its subclasses.
+
+A Result ``r`` contains four important fields:
+
+**type**
+  a :ref:`type` defining the kind of value this Result can hold in
+  computation.
+
+**owner**
+  this is either None or an :ref:`apply` node of which the Result is
+  an output.
+
+**index**
+  the integer such that ``owner.outputs[index] is r`` (ignored if
+  ``owner`` is None)
+
+**name**
+  a string to use in pretty-printing and debugging.
+
+Result has one special subclass: :ref:`constant <constant>`.
+
+
+
+.. index::
+   single: Op
+   single: graph construct; Op
+
+.. _op:
+
+--
+Op
+--
+
+WRITEME
+
+
+
+.. index::
+   single: Type
+   single: graph construct; Type
+
+.. _type:
+
+----
+Type
+----
+
+WRITEME
+

doc/advanced/index.txt

+
+.. _advanced:
+
+===============
+Advanced Topics
+===============
+
+.. toctree::
+   :maxdepth: 2
+   
+   graphstructures
+   env
+   optimization
+   compilation
+   function
+   module
+
+

doc/advanced/module.txt

+
+.. _moduleinterface:
+
+================
+Module Interface
+================
+
+WRITEME
+
+
+
+.. index::
+   single: Member
+   single: component; Member
+
+.. _member:
+
+------
+Member
+------
+
+WRITEME
+
+
+.. index::
+   single: Method
+   single: component; Method
+
+.. _method:
+
+------
+Method
+------
+
+WRITEME
+
+
+.. index::
+   single: Module
+   single: component; Module
+
+.. _module:
+
+------
+Module
+------
+
+WRITEME
+
+
+
+

doc/advanced/optimization.txt

+
+.. _optimization:
+
+============
+Optimization
+============

doc/advtutorial/index.txt

+
+.. _advtutorial:
+
+=================
+Advanced Tutorial
+=================
+
+Before tackling this tutorial, it is highly recommended to read the :ref:`basictutorial`.
+
+
+
+

doc/doc/glossary.txt → doc/glossary.txt

@@ -6,32 +6,132 @@ Glossary of terminology
 .. glossary::
 
     Apply
-        Op-related graph node (expression instance)
-        
-        An Apply instance (`Apply API <http://lgcm.iro.umontreal.ca/epydoc/theano.gof.graph.Apply-class.html>`_)
-        represents the application of an :term:`Op` on input :term:`Results <Result>`, producing output :term:`Results <Result>`.
-        Users typically do not instantiate Apply directly, instead they should use an Op's ``make_node`` or ``__call__`` function.
-        
-        Comparing with the Python language, an :term:`Apply` instance is theano's version of a function call (or expression instance) whereas :term:`Op` is theano's version of a function definition.
-        
-        An Apply instance serves as a simple structure with three important fields:
-          ``inputs``: a list of :term:`Result` instances that represent the arguments of the function.
-          ``outputs``: a list of :term:`Result` instances that represent the return values of the function.
-          ``op``: an Op instance that determines the function/transformation being applied here.
+        WRITEME
+
+    broadcasting
+        Broadcasting is a mechanism which allows tensors with
+        different numbers of dimensions to be added or multiplied
+        together by (virtually) replicating the smaller tensor along
+        the dimensions that it is lacking.
+
+        In a nutshell, broadcasting is the mechanism by which a scalar
+        may be added to a matrix, a vector to a matrix or a scalar to
+        a vector.
+
+        .. figure:: bcast.png
+
+           Broadcasting a row matrix. T and F respectively stand for
+           True and False and indicate along which dimensions we allow
+           broadcasting.
         
-        Theano.function uses the Apply instances' ``inputs`` field together with each :term:`Result`'s ``owner`` field to determine which inputs are necessary to compute the function's outputs.
-        Theano.function uses the Apply instances' ``op`` field to know how to compute the intermediate and final Results.
+        Unlike numpy which does broadcasting dynamically, Theano needs
+        to know, for any operation which supports broadcasting, which
+        dimensions will need to be broadcasted. When applicable, this
+        information is given in the :term:`Type` of a :term:`Result`.
 
-        See :ref:`intro_to_ops`.
+        For more information, see the article about broadcasting_.
         
-    Broadcasting
-        implicit tensor repmat
+        See also:
+
+        * `SciPy documentation about numpy's broadcasting <http://www.scipy.org/EricsBroadcastingDoc>`_
+        * `OnLamp article about numpy's broadcasting <http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html>`_
+
+    constant
+        WRITEME
+
+    elementwise
+        An elementwise operation ``f`` on two matrices ``M`` and ``N``
+        is one such that:
         
+        ``f(M, N)[i, j] = f(M[i, j], N[i, j])``
+
+        In other words, each element of an input matrix is combined
+        with the corresponding element of the other(s). There are no
+        dependencies between elements whose ``[i, j]`` coordinates do
+        not correspond, so an elementwise operation is like a scalar
+        operation generalized along several dimensions.
+
+        There exist unary, binary, ternary, etc. elementwise
+        operations and they can work on scalars, vectors, matrices,
+        etc. as long as all the inputs have the same dimensions or can
+        be :term:`broadcasted <broadcasting>` to the same dimensions.
+
+        Examples of elementwise operations in Theano: ``add, sub, mul,
+        div, neg, inv, log, exp, sin, cos, tan`` and many
+        others. These operations are all subclasses of :api:`Elemwise
+        <theano.tensor.elemwise.Elemwise>`.
+
+    graph
+        WRITEME
+
+    op
         WRITEME
+
+    Result 
+        A :ref:`result` is the main data structure you work with when
+        using Theano. The symbolic inputs that you operate on are
+        Results and what you get from applying various operations to
+        these inputs are also Results. For example, when I type
+
+        >>> x = theano.tensor.ivector()
+        >>> y = -x
+
+        ``x`` and ``y`` are both Results, i.e. instances of the
+        :api:`Result <theano.gof.graph.Result>` class. The
+        :term:`Type` of both ``x`` and ``y`` is
+        ``theano.tensor.ivector``.
+
+        For more information, see: :ref:`result`.
+
+    type
+        WRITEME
+
+
+.. _broadcasting: concepts/broadcasting.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+..
+    Apply
+        TRANSFERRED
         
-        The following pages appear to describe broadcasting, but I haven't read over them:
-           * http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html
-           * http://www.scipy.org/EricsBroadcastingDoc
+    Broadcasting
+        TRANSFERRED
         
     Build
         see :term:`Compilation`
@@ -52,14 +152,7 @@ Glossary of terminology
         The :term:`mode` defines how optimizations and stabilizations will be introduced, and defines which linker will be used.
 
     Constant
-        See :term:`Value`        
-        
-        Constant (`Constant API
-        <http://lgcm.iro.umontreal.ca/epydoc/theano.gof.graph.Constant-class.html
-        doc>`_) also has an additional property: it is forbidden for an
-        :term:`Op` to modify the state of the data it contains. This
-        makes it eligible to participate in numerous optimizations:
-        constant inlining in C code, constant folding, etc.
+        TRANSFERRED    
 
     DType
         the numeric type for :term:`Tensor` elements
@@ -90,100 +183,8 @@ Glossary of terminology
         WRITEME
 
     Graph
-        interconnected :term:`Apply` and :term:`Result` instances
-
-        In theano, a graph is an implicit concept, not a class or
-        an instance.  When we create :term:`Results <Result>` and
-        then :term:`apply` :term:`operations <Op>` to them to make
-        more Results, we build a bi-partite, directed, acyclic graph.
-        Results point to Apply instances (via the ``owner`` field)
-        and Apply instances point to Results (via their ``inputs``
-        and ``outputs`` fields).
-
-        To see how :term:`Result`, :term:`Type`, :term:`Apply`, and
-        :term:`Op` all work together, compare the following code fragment
-        and illustration.
-
-        .. code-block:: python
+        TRANSFERRED
 
-            #!python
-            x = matrix('x')
-            y = matrix('y')
-            z = x + y
-
-        .. image:: apply.png 
-
-        Arrows represent references (python's pointers), the blue box is an Apply instance, red boxes are :term:`Result` nodes, green circles are :term:`Op` instances, purple boxes are :term:`Type` instances.
-        
-        Short example:
-        
-        .. code-block:: python
-
-            #!python
-            from theano.tensor import *
-            
-            # create 3 Results with owner = None
-            x = matrix('x')
-            y = matrix('y')
-            z = matrix('z')
-            
-            # create 2 Results (one for 'e', one intermediate for y*z)
-            # create 2 Apply instances (one for '+', one for '*')
-            e = x + y * z
-
-        Long example:
-        
-        The example above uses several syntactic shortcuts.
-        If we had wanted a more brute-force approach to graph construction, we could have typed this.
-
-        .. code-block:: python
-
-            #!python
-            from theano.tensor import *
-            
-            # We instantiate a type that represents a matrix of doubles
-            float64_matrix = Tensor(dtype = 'float64',              # double
-                                    broadcastable = (False, False)) # matrix
-            
-            # We make the Result instances we need.
-            x = Result(type = float64_matrix, name = 'x')
-            y = Result(type = float64_matrix, name = 'y')
-            z = Result(type = float64_matrix, name = 'z')
-            
-            # This is the Result that we want to symbolically represents y*z
-            mul_result = Result(type = float64_matrix)
-            assert mul_result.owner is None
-            
-            # We instantiate a symbolic multiplication
-            node_mul = Apply(op = mul,
-                             inputs = [y, z],
-                             outputs = [mul_result])
-            assert mul_result.owner is node_mul and mul_result.index == 0 # these fields are set by Apply
-            
-            # This is the Result that we want to symbolically represents x+(y*z)
-            add_result = Result(type = float64_matrix)
-            assert add_result.owner is None
-            
-            # We instantiate a symbolic addition
-            node_add = Apply(op = add,
-                             inputs = [x, mul_result],
-                             outputs = [add_result])
-            assert add_result.owner is node_add and add_result.index == 0 # these fields are set by Apply
-            
-            e = add_result
-            
-            # We have access to x, y and z through pointers
-            assert e.owner.inputs[0] is x
-            assert e.owner.inputs[1] is mul_result
-            assert e.owner.inputs[1].owner.inputs[0] is y
-            assert e.owner.inputs[1].owner.inputs[1] is z
-
-        Note how the call to ``Apply`` modifies the ``owner``
-        and ``index`` fields of the :term:`Results <Result>` passed as
-        outputs to point to itself and the rank they occupy in the
-        output list. This whole machinery builds a DAG (Directed
-        Acyclic Graph) representing the computation, a graph that
-        theano can compile and optimize.
 
     Graph Transformation
         compilation stage
@@ -435,3 +436,4 @@ Glossary of terminology
         Theano computation). This can be practical because the compiler
         knows how to assign values to those nodes, thereby creating a
         sort of closure.
+..

doc/index.txt

 
+.. _theano:
+
 ======
 Theano
 ======
 
-.. toctree::
-   :maxdepth: 2
+Theano is a Python library aiming to allow definition, optimization
+and efficient evaluation of mathematical expressions involving
+multi-dimensional arrays (though it may be extended to support many
+other types). Theano melds some aspects of a computer algebra system
+(CAS) with aspects of an optimizing compiler. This is particularly
+useful in fields such as machine learning where complicated algorithms
+must be run over large amounts of data.
 
-   doc/README
-   doc/LICENSE
-   doc/index
+Theano supports a wide range of numerical types in multiple
+dimensions, a rapidly growing number of well-tested operations as well
+as utilities to compute the gradient of an expression with respect to
+another. Symbolic expressions may be compiled into functions, which
+work merrily on the same data structures as numpy_, allowing for easy
+interoperability.
 
--------------------------------------------------------------------
-A python library for manipulating and evaluating matrix expressions
--------------------------------------------------------------------
+Theano's compiler applies many optimizations of varying
+complexity. These optimizations include, but are not limited to
+constant folding, merging of similar subgraphs (to avoid calculating
+the same values more than once), simple arithmetic simplification
+(``x*y/x -> y``), inserting efficient BLAS_ operations and using
+inplace operations wherever it is safe to do so. Theano also defines
+several optimizations which improve the numerical stability of
+computations and it provides a framework to add and test new
+optimizers.
 
-Theano is a library and optimizing compiler in Python, built to
-evaluate complicated expressions (especially matrix-valued ones) as
-quickly as possible.  It was written at LISA_ to explore techniques
-for machine learning.  Our project uses the name to honour the ancient
-Greek mathematician.
+Theano was written at the LISA_ to support the development of
+efficient machine learning algorithms while minimizing human
+time. Theano was named after the `Greek mathematician`_ who may have
+been Pythagoras' wife.
 
---------------------------------------------------------------------------------
 
-.. _not in the normal sense: :wiki:`WhatIsTheano`
 
-Overview
-========
+Getting started
+===============
 
-**To get up and running quickly** see README_.
+TODO: I want to bold the links below. How the fuck do I bold links? ``**`link name`_**`` doesn't work! :(
 
-All **documentation** can be reached from the `Theano Project Documentation Overview`_.
 
-As developers of an open source project, we rely on **feedback** for
-determining what features to implement, and what documentation needs to be
-improved.  The best forum for feedback is the theano-users_ mailing list.
+:ref:`install`
+  Instructions to download and install Theano on your system.
 
-All **discussion** about theano also takes place on the theano-users_ mailing list.
 
-If you find a **bug**, please file a `bug report`_ or send email to
-the theano-users_ mailing list.  **Patch** submissions should be
-sent to theano-dev_.
+:ref:`basictutorial`
+  Getting started with Theano's basic features. Go there if you are new!
 
-We welcome all kinds of **contributions**.  Our `task list`_ is
-full of interesting ideas awaiting a champion.  If you have any
-questions regarding how to extend Theano, please feel free to ask on
-the Theano-dev_ mailing list.
 
-Theano is in active development and should be considered **experimental**.
-APIs are subject to change at any time.
+:ref:`advtutorial`
+  This tutorial is for more advanced users who want to define their own
+  operations and optimizations. It is recommended to go through the
+  :ref:`basictutorial` first.
 
 
-Download
+
+Contents
 ========
 
-We recommend that you use the `latest snapshot`_,
-Better yet, use `mercurial`_ to keep your installation fresh.
-The snapshots usually contain *more features* and *fewer bugs* than the
-"official" releases |---| they're not only for developers!
+.. toctree::
+   :maxdepth: 2
+
+   install
+   tutorial/index
+   advtutorial/index
+   advanced/index
+   indexes/index
+   glossary
+   LICENSE
 
 
-Indices and tables
-==================
+Contact us
+==========
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Discussion about Theano takes place in the theano-dev_ and
+theano-users_ mailing lists. People interested in development of
+Theano should check the former, while the latter is reserved for
+issues that concern the end users.
 
+Questions, comments, praise, criticism as well as bug reports should
+be submitted to these mailing lists.
+
+We welcome all kinds of contributions. Our `task list`_ is full of
+interesting ideas awaiting a champion.  If you have any questions
+regarding how to extend Theano, please feel free to ask on the
+theano-dev_ mailing list.
+
+
+
+.. _LISA:  http://www.iro.umontreal.ca/rubrique.php3?id_rubrique=27
+.. _Greek mathematician: http://en.wikipedia.org/wiki/Theano_(mathematician)
+.. _numpy: http://numpy.scipy.org/
+.. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
 
-.. |---| unicode:: U+02014 .. em dash
-   :trim:
-.. _latest snapshot: http://pylearn.org/hg/theano/archive/tip.tar.gz
-.. _bug report: http://lgcm.iro.umontreal.ca/theano/newticket
 .. _theano-users: http://groups.google.com/group/theano-users?pli=1
 .. _theano-dev: http://groups.google.com/group/theano-dev?pli=1
-.. _reStructuredText: rst.html
 .. _task list: http://lgcm.iro.umontreal.ca/theano/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
-.. _README: README.html
-.. _Quick-Start: README.html#quick-start
-
-.. _Theano Project Documentation Overview: doc/index.html
-.. _Mercurial: http://www.selenic.com/mercurial/wiki/
-.. _docutils: http://docutils.sourceforge.net
-.. _epydoc: http://epydoc.sourceforge.net/
-.. _scipy: http://scipy.org/
-.. _Python: http://www.python.org/
-.. _TRAC: http://trac.edgewall.org/
-.. _LISA:  http://www.iro.umontreal.ca/rubrique.php3?id_rubrique=27
+
 

doc/indexes/index.txt

+
+=======
+Indexes
+=======
+
+The following indexes are generated automatically and cover most
+:ref:`Ops <op>`, :ref:`Types <type>` and :ref:`Optimizers <optimizer>`
+in Theano.
+
+.. toctree::
+   :maxdepth: 1
+   
+   oplist
+   typelist
+

doc/install.txt

+
+.. _install:
+
+=================
+Installing Theano
+=================
+
+------------
+Requirements
+------------
+
+In order to use Theano, the following libraries and software will need
+to be installed:
+
+
+- linux or OS-X operating system
+- python >=2.5
+- numpy >=1.2 (earlier versions have memory leaks)
+- SciPy (specifically numpy, sparse, weave). We recommend scipy >=0.7 if you are using sparse matrices, because scipy.sparse is buggy in 0.6. (scipy.csc_matrix dot has a bug with singleton dimensions. There may be more bugs.)
+- g++, python-dev (optional but highly recommended, to compile generated C code)
+- docutils, pygments (optional, to build documentation)
+- mercurial (optional, to download the source)
+- nose (nosetests) (optional, for testing)
+
+
+------------
+Easy install
+------------
+
+The following command will install the very latest revision of Theano
+on your system:
+
+.. code-block:: bash
+    
+    easy_install http://pylearn.org/hg/theano/archive/tip.tar.gz
+
+TODO: make sure this works
+
+TODO: change the command to install the latest *stable* version of
+Theano, when we figure out where to put it.
+
+
+--------------
+Manual install
+--------------
+
+There are two ways to get the source: through mercurial (required for
+library developers) or through a unix compressed archive.  There are
+no stable releases yet.
+
+*To get the source via mercurial,* you must have `mercurial <http://www.selenic.com/mercurial/wiki/>`__ installed.
+
+Get the source and run the tests like this:
+
+.. code-block:: bash
+    
+    hg clone http://pylearn.org/hg/theano Theano
+    ln -s Theano/theano <someplace on your PYTHONPATH>/theano
+    cd Theano
+    nosetests #execute all the tests
+
+All tests should pass. If some test fails on your machine, you are
+encouraged to tell us what went wrong on the theano-users mailing
+list.
+
+The environment variable PYTHONPATH should be modified to tell Python
+where to find Theano. In bash, you may do this:
+
+.. code-block:: bash
+
+    export PYTHONPATH=<path to Theano/theano>:$PYTHONPATH
+
+In csh:
+
+.. code-block:: csh
+
+    setenv PYTHONPATH <path to Theano/theano>:$PYTHONPATH 
+
+To update your library to the latest revision, change directory (`cd`)
+to your `Theano` folder and execute the following command:
+
+.. code-block:: bash
+
+    hg pull -u
+
+You may also download the latest source directly as a gzip'd tar file:
+`<http://pylearn.org/hg/theano/archive/tip.tar.gz>`__.
+
+
+---------------------------
+Configuring the environment
+---------------------------
+
+Two environment variables are used to control automatic code
+generation. It is possible to use theano in a way which avoids all
+automatic code generation, but that way is much, much slower.
+
+- `THEANO_BLAS_LDFLAGS`: 
+    a space-separated list of library names to link against for BLAS functions. Default: `-lblas`
+
+- `THEANO_COMPILEDIR`:
+    a directory with read/write access permissions where theano will store
+    autogenerated code and c modules. Default: `$HOME/.theano`. If this
+    directory does not exist or does not have the correct permissions,
+    theano will try to create it with the correct permissions. If that fails,
+    an exception will be raised and no C code will be compiled.
+
+
+---
+Mac
+---
+
+- Install `MacPorts <http://www.macports.org/>`__.
+
+- `sudo port install gcc42 py25-zlib py25-numpy py25-scipy mercurial`.
+    Note that compiling gcc42 takes a significant time (hours) so it's probably
+    not the best solution if you're in a rush! In my (Doomie) experience, scipy
+    failed to compile the first time I tried the command, but the second time
+    it compiled just fine. Same thing with py25-zlib.
+
+- Install some kind of BLAS library (TODO: how?)
+
+- Set THEANO_BLAS_LDFLAGS to something which will link against said BLAS
+  library.  (e.g., `THEANO_BLAS_LDFLAGS='-lcblas -latlas -lgfortran'`).
+
+TODO: check if this is still valid
+
+
+-------
+Windows
+-------
+
+As of now, the Windows platform is not supported. In fact, it has
+never even been tested, so feel free to explore this uncharted
+territory and inform us of your progress!
+

doc/tutorial/adding.txt

+
+===========================
+Adding two numbers together
+===========================
+
+
+Adding two scalars
+==================
+
+So, to get us started and get a feel of what we're working with, let's
+make a simple function: add two numbers together. Here is how you do
+it:
+
+>>> x = T.dscalar('x')
+>>> y = T.dscalar('y')
+>>> z = x + y
+>>> f = function([x, y], z)
+
+And now that we've created our function we can use it:
+
+>>> f(2, 3)
+array(5.0)
+>>> f(16.3, 12.1)
+array(28.4)
+
+
+Let's break this down into several steps. The first step is to define
+two symbols, or Results, representing the quantities that you want to
+add. Note that from now on, we will use the term :term:`Result` to
+mean "symbol" (in other words, ``x``, ``y``, ``z`` are all Result
+objects).
+
+-------------------------------------------
+
+**Step 1**
+
+>>> x = T.dscalar('x')
+>>> y = T.dscalar('y')
+
+In Theano, all symbols must be typed. In particular, ``T.dscalar`` is
+the type we assign to "0-dimensional arrays of doubles". It is a
+Theano :term:`Type`. Therefore, you can guess that by calling
+``T.dscalar`` with a string argument, you create a :term:`Result`
+representing a floating-point scalar quantity with the given name (if
+you provide no argument, the symbol will be unnamed, which can cause
+difficulties in debugging).
+
+Note that ``dscalar`` is not a class and that therefore neither ``x``
+nor ``y`` are actually instances of ``dscalar``. They are instances of
+:api:`TensorResult <theano.tensor.basic.TensorResult>`. It is however
+assigned the theano Type ``dscalar`` in its ``type`` field, as you can
+see here:
+
+>>> type(x)
+<class 'theano.tensor.basic.TensorResult'>
+>>> x.type
+Tensor(float64, scalar)
+>>> T.dscalar
+Tensor(float64, scalar)
+>>> x.type == T.dscalar
+True
+
+Ditto for ``y``. You may learn more about the structures in Theano in
+the :ref:`advtutorial` and in :ref:`graphstructures`.
+
+-------------------------------------------
+
+**Step 2**
+
+The second step is to combine ``x`` and ``y`` into their sum ``z``:
+
+>>> z = x + y
+
+``z`` is yet another :term:`Result` which represents the addition of
+``x`` and ``y``. You can use the :api:`pp <theano.printing.pp>`
+function to print out the computation associated to ``z``.
+
+>>> print pp(z)
+x + y
+
+-------------------------------------------
+
+**Step 3**
+
+The last step is to create a function taking ``x`` and ``y`` as inputs
+and giving out ``z`` as output:
+
+>>> f = function([x, y], z)
+
+The first argument to ``function`` is a list of :term:`Results
+<Result>` that will be provided as inputs to the function. The second
+argument is a single Result that we want to see as output *or* a list
+of output results.
+
+``f`` may then be used like a normal Python function.
+
+
+Adding two matrices
+===================
+
+You might already have guessed how to do this. Indeed, the only change
+from the previous example is that you need to instantiate ``x`` and
+``y`` using the matrix Types:
+
+>>> x = T.dmatrix('x')
+>>> y = T.dmatrix('y')
+>>> z = x + y
+>>> f = function([x, y], z)
+
+``dmatrix`` is the Type for matrices of doubles. And then we can use
+our new function on 2D arrays:
+
+>>> f([[1, 2], [3, 4]], [[10, 20], [30, 40]])
+array([[ 11.,  22.],
+       [ 33.,  44.]])
+
+The result is a numpy array. We can also use numpy arrays directly as
+inputs:
+
+>>> import numpy
+>>> f(numpy.ones((3, 5)), numpy.ones((3, 5)))
+array([[ 2.,  2.,  2.,  2.,  2.],
+       [ 2.,  2.,  2.,  2.,  2.],
+       [ 2.,  2.,  2.,  2.,  2.]])
+
+It is possible to add scalars to matrices, vectors to matrices,
+scalars to vectors, etc. The behavior of these operations is defined
+by broadcasting_.
+
+The following types are readily available:
+
+* **byte**: bscalar, bvector, bmatrix
+* **32-bit integers**: iscalar, ivector, imatrix
+* **64-bit integers**: lscalar, lvector, lmatrix
+* **float**: fscalar, fvector, fmatrix
+* **double**: dscalar, dvector, dmatrix
+
+.. note::
+
+   Watch out for the distinction between 32 and 64 bit integers (i
+   prefix vs the l prefix) and between 32 and 64 bit floats (f prefix
+   vs the d prefix).
+
+
+Section
+-------
+
+Try to mix and match them and see what happens. A complete list of
+types compatible with numpy arrays may be found :ref:`here
+<typelist>`.
+
+
+**Next:** `More examples`_
+
+
+.. _broadcasting: ../concepts/broadcasting.html
+.. _More examples: examples.html

doc/tutorial/examples.txt

+
+.. _Basic Tutorial - More Examples:
+
+=============
+More examples
+=============
+
+
+Logistic function
+=================
+
+Let's say that you want to compute the logistic curve, which is given
+by:
+
+``s(x) = 1 / (1 + e**(-x))``
+
+You want to compute the function :term:`elementwise` on matrices of
+doubles.
+
+>>> x = T.dmatrix('x')
+>>> s = 1 / (1 + T.exp(-x))
+>>> logistic = function([x], s)
+
+Alternatively:
+
+>>> s = (T.tanh(x) + 1) / 2
+>>> logistic = function([x], s)
+
+
+Computing more than one thing at the same time
+==============================================
+
+Theano supports functions with multiple outputs. For example, we can
+compute the absolute :term:`elementwise` difference between two
+matrices ``x`` and ``y`` and the squared difference at the same time:
+
+>>> x, y = T.dmatrices('xy')
+>>> d = x - y
+>>> f = function([x, y], [abs(d), d**2])
+
+Theano will make ``f`` in such a way that it will only compute the
+difference once. When we use the function, it will return the two
+results (reformatted for readability):
+
+>>> f([[1, 1], [1, 1]], [[0, 1], [2, 3]])
+[array([[ 1.,  0.],
+        [ 1.,  2.]]),
+ array([[ 1.,  0.],
+        [ 1.,  4.]])]
+
+Also note the call to ``dmatrices``. This is a shortcut, use it wisely
+;)
+
+
+Computing gradients
+===================
+
+WRITEME
+
+
+Setting a default value for an argument
+=======================================
+
+WRITEME
+
+
+Making a function with state
+============================
+
+WRITEME
+
+
+**Next:** `Using Module`_
+
+.. _Using Module: module.html
+

doc/tutorial/index.txt

+
+.. _basictutorial:
+
+==============
+Basic Tutorial
+==============
+
+Before doing anything in this tutorial, make sure that Theano is
+installed on your system (see :ref:`install`).
+
+
+Done? Alright!
+
+
+Let's start an interactive session and import the package you just
+installed:
+
+>>> from theano import *
+
+Many of symbols you will need to use lie in the ``tensor`` subpackage
+of theano. Let's import that subpackage under a handy name. I like
+``T``.
+
+>>> import theano.tensor as T
+
+Now we're ready for the tour:
+
+---------------------------------------
+
+`Adding two numbers together`_
+  Starting small
+
+`More examples`_
+  Getting comfortable
+
+`Using Module`_
+  Getting serious
+
+---------------------------------------
+
+
+.. rubric:: Contents
+
+.. toctree::
+   :maxdepth: 2
+
+   adding
+   examples
+   module
+
+
+
+.. _Adding two numbers together: adding.html
+.. _More examples: examples.html
+.. _Using Module: module.html

doc/tutorial/module.txt

+
+============
+Using Module
+============
+
+WRITEME
+

scripts/docgen.py

@@ -75,12 +75,12 @@ if __name__ == '__main__':
 
     import gen_oplist
     print 'Generating oplist...'
-    gen_oplist.print_file(open('%s/doc/doc/oplist.txt' % throot, 'w'))
+    gen_oplist.print_file(open('%s/doc/indexes/oplist.txt' % throot, 'w'))
     print 'oplist done!'
 
     import gen_typelist
     print 'Generating typelist...'
-    gen_typelist.print_file(open('%s/doc/doc/typelist.txt' % throot, 'w'))
+    gen_typelist.print_file(open('%s/doc/indexes/typelist.txt' % throot, 'w'))
     print 'typelist done!'
 
     def mkdir(path):

scripts/gen_oplist.py

@@ -7,6 +7,7 @@ sys.path[0:0] = [theano_path]
 from theano import gof
 
 def print_title(file, title_string, under_char, over_char=''):
+
     l = len(title_string)
     if over_char:
         print >>file, over_char * l
@@ -157,6 +158,8 @@ def print_entries(file, ops, constructors):
 
 def print_file(file):
 
+    print >>file, '.. _oplist:\n\n'
+
     print_title(file, "Op List", "~", "~")
     print >>file, """
 This page lists the `Op Classes` and `constructors` that are provided by the Theano library.

scripts/gen_typelist.py

@@ -4,6 +4,8 @@ from gen_oplist import print_title, print_hline
 
 def print_file(file):
 
+    print >>file, '.. _typelist:\n\n'
+
     print_title(file, "Type List", "~", "~")
 
     print >>file, "*THIS PAGE IS A PLACEHOLDER: WRITEME*"