Arrows represent references (python's pointers), the blue box is an Apply instance, red boxes are `Result` nodes, green circles are `Op` instances, purple boxes are `Type` instances.
Two examples
============
Here's how to build a graph the convenient way...
.. 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
============
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
from theano.tensor import *
# We instantiate a type that represents a matrix of doubles
# 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 `Result` s 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.
- 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)
- sphinx >=0.5.1, pygments (optional, to build documentation) (also latex and dvipng if you want math to show up as images...)
- mercurial (optional, to download the source)
- nose (nosetests) (optional, for testing)
...
...
@@ -134,3 +134,19 @@ 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!
----------------------------
Generating the documentation
----------------------------
This should give you the gist of it:
.. code-block:: bash
$ python scripts/docgen.py --help
Usage: scripts/docgen.py [OPTIONS]
-o <dir>: output the html files in the specified dir
--rst: only compile the doc (requires sphinx)
--epydoc: only compile the api documentation (requires epydoc)
