
.. _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.

