added graphstructures to the doc, added install guide

doc/advanced/graphstructures.txt

+
+.. _graphstructures:
+
+================
+Graph Structures
+================
+
+
+.. 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
+

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!
+