merge

doc/README.txt

@@ -8,7 +8,7 @@ README: theano
 Project Description
 ===================
 
-Theano is a python library for manipulating and evaluating expressions, especially matrix-valued ones.
+Theano is a python library and optimizing compiler for manipulating and evaluating expressions, especially matrix-valued ones.
 What does Theano do that Python and numpy do not?
 
 - *execution speed optimizations*: Theano can use `g++` to compile parts your expression graph into native machine code, which runs much faster than python.
@@ -37,13 +37,17 @@ Here's a very simple example of how to use Theano.  It doesn't show off many of
 
 Theano is not a programming language in the normal sense because you write a program in Python that builds expressions for Theano.  Still it is like a programming language in the sense that to use theano, you have to 
 
-- declare variables ({{{a,b}}}) and give their types
+- declare variables (``a,b``) and give their types
 
 - build expressions for how to put those variables together
 
 - compile expression graphs to functions in order to use them for computation.
 
-It is good to think of `theano.function` as the interface to a compiler which builds a callable object from a purely symbolic graph.
+It is good to think of ``theano.function`` as the interface to a compiler
+which builds a callable object from a purely symbolic graph; one of
+theano's most important features is that ``theano.function`` can
+optimize a graph, and even compile some or all of it into native machine
+instructions if you pass ``linker='c'`` as a keyword argument.
 
 
 License
@@ -55,9 +59,6 @@ Theano is licensed under a BSD-like license.  See the LICENSE file in the projec
 Installation
 ============
 
-(See also the :wiki:`InstallationNotes` on the wiki.)
-
-
 Software Requirements
 ---------------------
 
@@ -94,15 +95,24 @@ Get the source and run the tests like this:
     cd Theano
     nosetests #execute all the tests
 
-All tests should pass. From time to time, their is some test that are know to fail, but normally we know them and are trying to fix them. But to be sure contact us about them. 
+All tests should pass. From time to time, there is some test that are
+know to fail, but normally we know them and are trying to fix them. But
+to be sure contact us about them.
 
-To define PYTHONPATH if it don't exist:
+The environment variables PYTHONPATH should be modified to allow python
+import. In bash do this: 
 
 .. code-block:: bash
-export PYTHONPATH=<path to theano>:$PYTHONPATH
 
+    export PYTHONPATH=<path to theano>:$PYTHONPATH
+
+In csh:
+
+.. code-block:: csh
+
+    setevn PYTHONPATH <path to theano>:$PYTHONPATH 
 
-To update your library to the latest on pylearn.org, change directory (`cd`) to this `theano` folder and type
+To update your library to the latest on pylearn.org, change directory (`cd`) to this `Theano` folder and type
 
 .. code-block:: bash
 
@@ -112,7 +122,7 @@ To update your library to the latest on pylearn.org, change directory (`cd`) to
 `<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 that avoids all automatic code generation, but the functions you make using {{{theano.function}}} will execute more slowly.)
@@ -184,6 +194,14 @@ Use something like the following in your .bashrc:
     # Theano is not process-safe or thread-safe in this sense.
     THEANO_COMPILEDIR=/ltmp/<username>_theano
 
+You may also need to run the following from your shell: 
+
+.. code-block:: bash
+
+    module add python      # for the current shell session 
+    module initadd python  # for this and future sessions 
+
+Lastly,  if ``./filename.py`` doesn't work, try ``python filename.py``.
 
 Running the Test Suite
 ======================
@@ -197,13 +215,13 @@ Test your installation by running the tests.  Type at the shell:
 
 All tests should pass.
 
-python-nose must be installed. On red-hat or fedora core: sudo yum install python-nose.noarch
+python-nose must be installed. On red-hat or fedora core: ``sudo yum install python-nose.noarch``
 
 
 Using Theano
 ============
 
-Now that you've got theano installed and running, check out the `n00b tutorial <doc/n00b.html>`__ for how to use it.
+Now that you've got theano installed and running, check out the `tutorial <doc/tutorial.html>`__ for how to use it.
 
 
 Getting Help

doc/doc/extending.txt

+================
+Extending theano
+================
+
+This page introduces some important terminology for describing how theano
+works.  Below there is a list of HOWTO documents for extending theano.
+
+Lets start by looking at what happens in a simple theano program.
+
+.. code-block:: python
+
+    #!python
+    x = tensor.matrix('x')
+    y = tensor.matrix('y')
+    z = x + y
+    f = theano.function(input=[x,y], output=z, mode='FAST_RUN')
+    print f(numpy.ones(2,3), numpy.ones(2,3))
+
+The first three lines build a graph_ whose nodes correspond to variables (``x,y,z``) and expressions (just the '+' here).
+The variables in such a graph are Result_ instances of some Type_, and the expressions are Apply_ instances of some Op_.
+
+The line ``f = theano.function([x,y], [z], mode='FAST_RUN')`` compiles_
+the graph we built and returns a function_ whose ``__call__`` method
+takes as arguments the values to use for ``x`` and ``y``.
+The mode_ controls which transformations_ are applied to the graph as we compile it.
+
+The line ``print f(numpy.ones(2,3), numpy.ones(2,3))`` creates two
+matrices, and then uses f's ``__call__`` method to run the compiled
+function on those inputs.
+The compiled function is executed by a linker_, which was also specified by the mode_ argument to ``function``.
+The instance f's ``__call__`` method returns a value for ``z`` (given ``x,y``) which we print.
+
+Theano was designed to be extensible to new types_ of Result, new Ops_ to use in symbolic computations,
+and new modes of compilation and execution.  When you're comfortable with the material above, move on to:
+
+* HowtoCreateType create a new data type,
+* HowtoCreateOp create a new type of Op,
+* HowtoAddTransformation add a transformation to an existing transformation mode,
+* Create a new mode by HowtoCreateLinker creating a new linker, or HowtoCreateTransformationMode create a new transformation mode.
+

doc/doc/index.txt

@@ -37,7 +37,7 @@ Using Theano
 .. _Howto: 
 .. _theano-users: http://groups.google.com/group/theano-users?pli=1
 .. _theano-dev: http://groups.google.com/group/theano-dev?pli=1
-.. _n00b guide: n00b.html
+.. _tutorial: tutorial.html
 .. _glossary of terminology: ../api/term-index.html
 .. _typelist: typelist.html
 .. _oplist: oplist.html
@@ -48,6 +48,8 @@ Extending Theano
 - Read about `How Theano Works <UserAdvanced.html>`__.  This introduces the
   major interface data structures: Op, Type, Result, Apply.
 
+- Read about `Extending theano <extending.html>`__.
+
 - How to make a new Op.
 
 - How to make a new Optimization.

doc/doc/n00b.txt → doc/doc/tutorial.txt

 =============
-n00b Tutorial
+Tutorial
 =============
 
 .. contents::
@@ -44,14 +44,16 @@ In the following example, we will build a function `f(x) = x + 1.5`. We will the
     f = theano.function([x], [y])
 
     # We now bind 2.5 to an internal copy of x and evaluate an internal y,
-    # which we return.
-    # We assert that 4.0 == f(2.5) = 2.5 + 1.5
-    assert 4.0 == f(2.5)
+    # which we return (actually f(2.5) returns a list because theano 
+    # functions in general can return many things). 
+    # We assert that 4.0 == f(2.5)[0] = 2.5 + 1.5 
+    assert 4.0 == f(2.5)[0] 
 
-In the example above, `c`, `x`, and `y` are each a ''symbolic'' result_. They
-are symbolic because they stand for variables and have a type_, but
-do not necessarily store actual values.  Not yet, at least.  (To give them
-values, we will have to `evaluate` them.  More on this below.)
+In the example above, `c`, `x`, and `y` are each a ''symbolic''
+result_. They are symbolic because they stand for variables and have
+a type_, but do not actually store instantiated variables.  Not yet,
+at least.  (To give them values, we will have to `evaluate` them.
+More on this below.)
 
 .. _result: glossary.html#result
 .. _type: glossary.html#type
@@ -60,14 +62,15 @@ Since we are using the addition operator (`x + c`) here on symbolic results, the
 output `y` is also symbolic.  The `+` corresponds to an ''operation'' in theano
 terminology, or ''op'' for short.
 
-We use these results and ops to construct a `symbolic graph`_.  The graph is
-symbolic because we declare what it computes, but do not actually perform any
-computation.  Some type-checking is done on while we build our graphs, so if you
-try to do something really crazy you'll see an exception right away.
+We use these results and ops to construct a `symbolic graph`_. The graph
+is symbolic because we declare what it computes, but do not actually
+perform any computation.  Some type-checking is done on while we build
+our graphs, so if you try to do something really crazy you'll see an
+exception right away.
 
 .. _symbolic graph: glossary.html#symbolicgraph
 
-To actually use our graph for computation, we have to compile (or build) it into
+To actually use our graph for computation, we have to compile_ (or build_) it into
 a function `f`.   The compiled function is actually capable of performing
 computation.  So after we have built f, we use it to compute the value of y from
 a `value input` x.  Some argument checking is only possible at run-time, so if
@@ -84,7 +87,7 @@ and we are working hard to make these problems errors easier to fix.
 *It would be worth thinking through the order in which these terms should be introduced.
 Can we inline the text?'''*
 
-*Note: Theano has two types of [DefineScalar scalar].*
+*Note: Theano has two types of scalar_.*
 
 Matrix example
 ==============

doc/index.txt

@@ -13,10 +13,11 @@ Theano
 A python library for manipulating and evaluating matrix expressions
 -------------------------------------------------------------------
 
-Theano is a library 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 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.
 
 --------------------------------------------------------------------------------