added many stubs to the advanced section of the docs

Author: breuleux

LICENSE.txt

@@ -1 +1 @@
-doc/doc/LICENSE.txt
+doc/LICENSE.txt

doc/apply.png doc/advanced/apply.png

@@ -0,0 +1,6 @@
+
+.. _compilation:
+
+=======================
+Compilation and Linking
+=======================

doc/advanced/compilation.txt

@@ -0,0 +1,6 @@
+
+.. _env:
+
+===
+Env
+===

doc/advanced/env.txt

@@ -0,0 +1,50 @@
+
+.. _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/function.txt

@@ -5,6 +5,139 @@
 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

doc/advanced/graphstructures.txt

@@ -9,4 +9,10 @@ Advanced Topics
    :maxdepth: 2
 
    graphstructures
+   env
+   optimization
+   compilation
+   function
+   module
+
 

doc/advanced/index.txt

@@ -0,0 +1,52 @@
+
+.. _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/module.txt

@@ -0,0 +1,6 @@
+
+.. _optimization:
+
+============
+Optimization
+============

doc/advanced/optimization.txt

@@ -183,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
-
-            #!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
+        TRANSFERRED
 
-            #!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

doc/glossary.txt

@@ -69,6 +69,7 @@ Contents
    advtutorial/index
    advanced/index
    indexes/index
+   glossary
    LICENSE