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)
- 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.)
- 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)
- 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)
- mercurial (optional, to download the source)
- nose (nosetests) (optional, for testing)
- nose (nosetests) (optional, for testing)
...
@@ -134,3 +134,19 @@ As of now, the Windows platform is not supported. In fact, it has
...
@@ -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
never even been tested, so feel free to explore this uncharted
territory and inform us of your progress!
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)
