
.. _introduction:

==================
Theano at a Glance
==================

Theano is a Python library that lets you to define, optimize, and evaluate
mathematical expressions, especially ones with multi-dimensional arrays
(numpy.ndarray).  Using Theano it is
possible to attain speeds rivaling hand-crafted C implementations for problems
involving large amounts of data.  It can also surpass C on a CPU by many orders
of magnitude by taking advantage of recent GPUs.

Theano combines aspects of a computer algebra system (CAS) with aspects of an
optimizing compiler. It can also generate customized C code for many
mathematical operations.  This combination of CAS with optimizing compilation
is particularly useful for tasks in which complicated mathematical expressions
are evaluated repeatedly and evaluation speed is critical.  For situations
where many different expressions are each evaluated once Theano can minimize
the amount of compilation/analysis overhead, but still provide symbolic
features such as automatic differentiation.

Theano's compiler applies many optimizations of varying complexity to
these symbolic expressions. These optimizations include, but are not
limited to:

* use of GPU for computations
* constant folding
* merging of similar subgraphs, to avoid redundant calculation
* arithmetic simplification (e.g. ``x*y/x -> y``, ``--x -> x``)
* inserting efficient BLAS_ operations (e.g. ``GEMM``) in a variety of
  contexts
* using memory aliasing to avoid calculation
* using inplace operations wherever it does not interfere with aliasing
* loop fusion for elementwise sub-expressions
* improvements to numerical stability (e.g.  :math:`\log(1+\exp(x))` and :math:`\log(\sum_i \exp(x[i]))`)
* for a complete list, see :ref:`optimizations`

Theano was written at the LISA_ lab to support rapid development of
efficient machine learning algorithms. Theano is
named after the `Greek mathematician`_, who may have been Pythagoras'
wife.  Theano is released under a BSD license (:ref:`link <license>`).


Sneak peek
==========

Here is an example of how to use Theano. It doesn't show off many of
Theano's features, but it illustrates concretely what Theano is.


.. If you modify this code, also change :
.. theano/tests/test_tutorial.py:T_introduction.test_introduction_1

.. code-block:: python

    import theano
    from theano import tensor

    # declare two symbolic floating-point scalars
    a = tensor.dscalar()
    b = tensor.dscalar()

    # create a simple expression
    c = a + b

    # convert the expression into a callable object that takes (a,b)
    # values as input and computes a value for c
    f = theano.function([a,b], c)

    # bind 1.5 to 'a', 2.5 to 'b', and evaluate 'c'
    assert 4.0 == f(1.5, 2.5)


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 you have to

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


What does it do that they don't?
================================

Theano is a Python library and optimizing compiler for manipulating
and evaluating expressions, especially matrix-valued
ones. Manipulation of matrices is typically done using the numpy
package, so what does Theano do that Python and numpy do not?

- *execution speed optimizations*: Theano can use `g++` or `nvcc` to compile
  parts your expression graph into CPU or GPU instructions, which run
  much faster than pure Python.

- *symbolic differentiation*: Theano can automatically build symbolic graphs
  for computing gradients.

- *stability optimizations*: Theano can recognize [some] numerically unstable
  expressions and compute them with more stable algorithms.

The closest Python package to Theano is sympy_.
Theano focuses more on tensor expressions than Sympy, and has more machinery
for compilation.  Sympy has more sophisticated algebra rules and can
handle a wider variety of mathematical operations (such as series, limits, and integrals).

If numpy_ is to be compared to MATLAB_ and sympy_ to Mathematica_,
Theano is a sort of hybrid of the two which tries to combine the best of
both worlds.


Getting started
===============

:ref:`install`
  Instructions to download and install Theano on your system.

:ref:`tutorial`
  Getting started with Theano's basic features. Go here if you are
  new!

:ref:`libdoc`
  Details of what Theano provides. It is recommended to go through
  the :ref:`tutorial` first though.


A PDF version of the online documentation may be found `here
<http://deeplearning.net/software/theano/theano.pdf>`_.


Contact us
==========

Discussion about Theano takes place in the theano-dev_ and
theano-users_ mailing lists. People interested in development of
Theano should check the former, while the latter is reserved for
issues that concern the end users.

Questions, comments, praise, criticism as well as bug reports should
be submitted to these mailing lists.

We welcome all kinds of contributions. If you have any questions
regarding how to extend Theano, please feel free to ask on the
theano-dev_ mailing list.



.. _LISA:  http://www.iro.umontreal.ca/rubrique.php3?id_rubrique=27
.. _Greek mathematician: http://en.wikipedia.org/wiki/Theano_(mathematician)
.. _numpy: http://numpy.scipy.org/
.. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms

.. _sympy: http://code.google.com/p/sympy/
.. _MATLAB: http://www.mathworks.com/products/matlab/
.. _Mathematica: http://www.wolfram.com/products/mathematica/index.html

.. _theano-users: http://groups.google.com/group/theano-users?pli=1
.. _theano-dev: http://groups.google.com/group/theano-dev?pli=1


