merged doc/advanced -> doc/sandbox

doc/advanced/module.txt

-
-.. _moduleinterface:
-
-================
-Module Interface
-================
-
-A Theano Module is like Theano's version of a file.
-When you instantiate a ``Module()``, you are creating a blank file.
-Into this file you can put both symbolic and non-symbolic objects.
-Non-symbolic objects are like constants (technically literals) in the file.
-Symbolic objects are like variables and functions.
-The functions in a Module are called Methods.
-The variables in a Module (and submodules) are global.
-Module Methods have access to all these global variables.
-
-To use a Module, you need to compile it.
-This is done by calling `Module.make()`.
-The result of compiling a Module is a ModuleInstance, this is the compiled
-version of your Theano file.
-In the ModuleInstance, your symbolic variables have become containers (containing None),
-and your Methods have become callable functions.
-You should initialize the symbolic variables by calling
-``ModuleInstance.initialize()`` (although make() will call it for you, 
-on the top-level ModuleInstance.)
-
-You can compile a Module several times, to create multiple ModuleInstances.
-Each of these will have its own copy of all program literals.
-
-
-
-Module Graph
-------------
-
-Components can be grouped into a directed graph.
-When we call `make`, this graph is replicated with ComponentInstances instead of
-Components.  Wheras Components are represent symbolic things (ie. Variables), ComponentInstances represent non-symbolic ones (ie. sparse matrices, ndarrays, callable functions).
-
-
-.. index::
-   single: Component
-   single: component; Component
-
-.. _component:
----------
-Component
----------
-
-All of the elements of what is called the "module system" or "modules" are
-components.
-
-A component subclass is represents a symbolic theano thing, and implements the
-``build`` function. 
-The ``build`` function is responsible for converting the symbolic thing into a
-non-symbolic thing.
-
-
-Compiling with make
--------------------
-
-Conversion from a Component graph to a ComponentInstance graph is performed by `Component.make`.
-This method traverses the Component graph in multiple passes. 
-
-In the first pass (the allocate pass), it creates storage for all Variables that are contained in the graph (see
-`Component.allocate`).  These are the module variables.
-
-In the second pass (the build pass), it creates functions that (in general) operate on these module variables.
-This pass also serves to construct all ComponentInstance-derived instances as well, such as
-`ModuleInstance`s.  The objects that are returned from this second pass are the return value of
-`Component.make`.
-
-In the third pass (the initialize pass), is optional and not necessarily recursive through the
-graph.
-The purpose of the third pass is to call the initialize method of the ComponentInstances built
-during the second pass.
-During this pass the ComponentInstance graph is complete. It is a good time to fill storage
-allocated in phase 1 with sensible values.
-
-.. index::
-   single: External
-   single: component; External
-
-.. _external:
---------
-External
---------
-
-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
-------
-
-A Module instance can contain objects as attributes.
-This makes it something like a class in the way that Method is
-analogous to a function.
-
-A Module is meant to contain Components.
-Attributes which are not Components themselves must at least be transform-able
-into Components by :api:`compile.module.wrap`.  If a Module contains something
-that is not convertible into a Component, then it is not possible to compile
-that Module with ``make``.
-
-
-Old Text
---------
-
-In the Module system, the analog of the file is the `Module`, the analog of the function is the
-`Method`, and the analog of the variable is the `Member`.  Module, Member, and Method all work
-at the symbolic level.  Once a graph of Modules, Members, and Methods is ready for use, it must
-be compiled with a call to `make` which will return an isomorphic structure in which Modules
-have become `ModuleInstances`, Members have become `Container`s, and Methods have become
-`Function`s.
-This structure contains numbers and functions, and is ready for computation.
-