
.. _install:


Installing Theano
=================

.. note::
    If you are a member of LISA Labo, have a look at :ref:`lisa_labo` for
    lab-specific installation instructions.


Requirements
------------

In order to use Theano, the following libraries and software will need
to be installed:

    Linux, OS-X or Windows operating system
        We develop mainly on 64-bit Linux machines. 32-bit architectures are
        not well-tested.

    python >= 2.5 (2.4 should be supported as well)

    `numpy <http://numpy.scipy.org/>`_ >= 1.3.0
        Earlier versions have memory leaks.
    `SciPy <http://scipy.org>`_
        Specifically numpy, sparse, and 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.)

    A BLAS installation (with Level 3 functionality), including the development
	headers	(-dev, -devel, depending on your Linux distribution).

The following libraries and software are optional:

    g++, python-dev
        Highly recommended, to compile generated C code.
    `nose <http://somethingaboutorange.com/mrl/projects/nose/>`_
        Recommended, to run Theano's test-suite.
    `sphinx <http://sphinx.pocoo.org/>`_ >=0.5.1, `pygments <http://pygments.org/>`_
        Used to build documentation. latex and dvipng
        are also necessary for math to show up as images.
    `mercurial <http://www.selenic.com/mercurial/>`_
        To download bleeding-edge version of Theano.

.. _install_bleeding_edge:

Getting the code
-----------------

If you are a developer of Theano, then check out the :ref:`dev_start_guide` guide. 

The following are general instructions that will set you up with the bleeding-edge 
version of Theano. First, get the code using `mercurial <http://www.selenic.com/mercurial/wiki/>`__:

.. code-block:: bash

    hg clone http://hg.assembla.com/theano Theano

Configuring PYTHONPATH
---------------------------

The subdirectory Theano/theano has to be located in a path
mentioned in your PYTHONPATH. In order to do that, you can either
create a symbolic link to Theano/theano in a directory already
mentioned in your PYTHONPATH environment variable, or modify the
PYTHONPATH so that it mentions Theano.

To create a symbolic link:

.. code-block:: bash

    ln -s Theano/theano <someplace on your PYTHONPATH>/theano

To modify the environment variable PYTHONPATH in bash, you may do this:

.. code-block:: bash

    export PYTHONPATH=<path to Theano's parent dir>/Theano:$PYTHONPATH

In csh:

.. code-block:: csh

    setenv PYTHONPATH <path to Theano's parent dir>/Theano:$PYTHONPATH

Troubleshooting: Make sure you have a BLAS library
-----------------------------------------------------

There are many ways to configure BLAS for Theano. This is done with the 
Theano flags blas.ldflags (:ref:`libdoc_config`). The default is to use
the blas installation information in numpy, accessible via ``numpy.distutils.__config__.show()``.
You can tell theano to use a different
version of BLAS, in case you didn't compile numpy with a fast BLAS or if numpy was compiled with a 
static library of blas (the latter is not supported in theano).

The short way to configure the theano flags blas.ldflags is by setting the
environmental variable ``THEANO_FLAGS`` to ``blas.ldflags=XXX``
(in bash ``export THEANO_FLAGS=blas.ldflags=XXX``)

The ``${HOME}/.theanorc`` file is the simplest way to set a relatively permanent
option like this one.  Add a ``[blas]`` section with an ``ldflags``
entry like this:

.. code-block:: text

    # other stuff can go here
    
    [blas]
    ldflags = -lf77blas -latlas -lgfortran #put your flags here

    # other stuff can go here

For more information on the formatting of ``~/.theanorc`` and the configuration options that you can put there, 
see :ref:`libdoc_config`.

Here are some different way to configure BLAS:

0) Do nothing and use the default config, which is to link against the same BLAS that numpy was built with. This doesn't work in the case numpy was compiled with a static library (e.g. ATLAS is compiled by default only as a static lib). 

1) Disable the usage of BLAS and fall back on numpy for dot products. To do this, set the value of blas.ldflags as the empty string (ex: ``export THEANO_FLAGS=blas.ldflags=``). Depending on the kind of matrix operations your theano code performs, this might slow some things down (vs. linking with BLAS directly).

2) You can install the default (reference) version of BLAS if the numpy version (which theano links against) doesn't work. If you have root or sudo access in fedora you can do ``sudo yum install blas blas-devel``. Under Ubuntu/Debian ``sudo apt-get install libblas-dev``. Then put the theano flags ``blas.ldflags=-lblas``. Not that the default version of blas is not optimized. Using an optimized version can give up to 10x speedups in the BLAS functions that we use.

3) Install the ATLAS library. ATLAS is an open source optimized version of BLAS. You can install a precompiled version on most OSes, but if you're willing to invest the time, you can compile it to have a faster version (we have seen speed-ups of up to 3x, especialy on more recent computers, against the precompiled one). On Fedora, ``sudo yum install atlas-devel``. Under Ubuntu, ``sudo apt-get install libatlas-base-dev libatlas-base`` or ``libatlas3gf-sse2`` if your CPU supports SSE2 instructions. Then set the theano flags ``blas.ldflags`` to ``-lf77blas -latlas -lgfortran``. Note that these flags are sometimes OS dependent.

4) Use a faster version like MKL, GOTO, ... You are on your own to install it. See the doc of that software and set the theano flags ``blas.ldflags`` correctly (for example, for MKL this might be ``-lmkl -lguide -lpthread`` or ``-lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core -lguide -liomp5 -lmkl_mc -lpthread``).

.. note::

    Make sure your BLAS
    libraries are available as dynamically-loadable libraries.  
    ATLAS is often installed only as a static library.  Theano is not able to
    use this static library.  ATLAS might need to be reinstalled or upgraded or
    something to provide dynamically loadable libraries.  (On Linux this
    typically means a library whose name ends with .so. On Windows this will be
    a .dll, and on OS-X it might be either a .dylib or a .so)

    This might be just a problem with the way Theano passes compilation
    arguments to gcc, but the problem is not fixed yet.


Testing your installation
---------------------------

Once you have completed these steps, you should run the theano test suite like this:

.. code-block:: bash

    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@googlegroups.com``
mailing list.

Updating
-------------


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 should update frequently, bugs are fixed on a very regular basis.

Mac
---

- If the above required libraries are not already installed on your Mac, one option is first, to
  install `MacPorts <http://www.macports.org/>`__.

- Then, in order to install one or more of the required libraries, use "port install", e.g. as follows:

    .. code-block:: bash

        $ sudo port install gcc44 py25-scipy mercurial python_select

    This will install all the required theano dependencies.  Note that
    compiling gcc takes significant time (hours)! SciPy depends on ATLAS (a
    good BLAS implementation) and numpy, so these will be installed for you automatically.

- You might have some old versions of gcc, SciPy, numpy, Python installed on
  your system, perhaps via XCode. It is a good idea to use **either** the
  MacPorts version of everything **or** some other set of compatible versions
  (provided by fink, or by XCode). The advantages of MacPorts are the
  transparency with which everything can be installed and the fact that
  packages are updated quite frequently.

- In order to use the MacPorts version of python, you might
  need to explicitly select it with ``sudo python_select python25``. The
  reason this is necessary is because you might have an Apple-provided python
  (via, for example, an XCode installation). After performing this step, you
  should check that the symbolic link provided by ``which python`` points to
  the MacPorts python. For instance, on Snow Leopard with the latest MacPorts, 
  the output of ``which python`` is ``/opt/local/bin/python`` and this symbolic
  link points to ``/opt/local/bin/python2.5``. When executing ``sudo
  python_select python26-apple`` (which you should **not** do), the link
  points to ``/usr/bin/python2.6``.

- Once this is fixed, please check that the scipy module that is imported in
  Python is the right one (and is a recent one). For instance, ``import
  scipy`` followed by ``print scipy.version`` and ``print scipy.__path__``
  should result in a version number of at least 0.7.0 and a path that starts
  with ``/opt/local`` (the path where MacPorts installs its packages). If this
  is not the case, then you might have some old installation of ``scipy`` in your
  ``PYTHONPATH`` so you should edit ``PYTHONPATH`` accordingly.

- Please follow the same procedure with ``numpy``.

- Put ``export PYTHONPATH=/opt/local/lib/python2.5/site-packages:$PYTHONPATH``
  in your ``.bashrc`` in order to include your MacPorts Python packages 
  (numpy, scipy) in Python's path.

- Make sure that the gcc version that you have installed on your system is
  up-to-date (at the very least 3.4, but 4.x is better). If you have an old
  version of XCode lying around, chances are that your gcc install is old. You
  should also check  ``which gcc``: if it says  ``/usr/bin/gcc`` then you
  should install gcc_select from MacPorts (``sudo port install gcc_select``)
  and use the MacPorts-provided gcc. Use ``gcc_select -l`` to see which gcc
  installs you have on the system. Then execute ``sudo gcc_select mp-gcc44``
  to create a symlink that points to the correct (MacPorts) gcc (version 4.4
  in this case).

- This is covered in the MacPorts installation process, but make sure that
  your ``PATH`` environmental variable contains ``/opt/local/bin`` and
  ``/opt/local/sbin`` before any other paths (to ensure that the python and
  gcc binaries that you installed with MacPorts are visible first).

- Likewise, you need to
  ``export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH`` if this is not
  the case already (so that we link to the correct libraries).

- An obscure ``Bus error`` can sometimes be caused when linking
  Theano-generated object files against the ``framework`` library in Leopard.
  For this reason, we've disabled linking with ``-framework Python``, since on 
  most configurations this solves the ``Bus error`` problem. If this default
  configuration causes problems with your Python/theano installation and you think
  that linking with ``-framework Python`` might help, then either set
  ``THEANO_FLAGS=cmodule.mac_framework_link`` or edit your ``~/.theanorc`` to
  contain

    .. code-block:: bash

      [cmodule]
      mac_framework_link=True

Please infom us if you have trouble installing and running Theano on your mac.
We would be especially interested in dependencies that we missed listing, as well as tests
that fail on your platform (use the ``theano-users@googlegroups.com`` mailing list,
but note that you must first register to it, by going to `theano-users`_).


Windows
-------

Running Theano under Windows is currently achieved by using the `MinGW
<http://www.mingw.org>`__ port of the GCC compiler.
It could probably also run with `Cygwin <http://www.cygwin.com/>`__,
but this has not been tested yet.

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest version of the ``Automated MinGW Installer`` and install
  it (keeping default options).

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest ``MSYS Base System`` executable file and run it
  (note that the latest version of MSYS Base System may not contain an
  executable file, in which case it is easier to just use an
  older version, e.g. MSYS-1.0.11.exe).
  This will install MSYS (you can keep the default install options).
  It will also run a post-install script where it will ask you about the
  location of MinGW (typically ``c:/MinGW``).

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the current version of ``GCC Version 4`` (full package with
  binaries, e.g.
  gcc-full-4.4.0-mingw32-bin-2.tar.lzma). Unpack it (you may use
  `7-Zip <http://www.7-zip.org>`__ to unpack files with the
  .lzma extension), copying the content into the root directory
  of your MinGW installation (if you obtain a .tar file, make
  sure you expand it as well, either with `7-Zip <http://www.7-zip.org>`__
  or through the ``tar`` command on the MSYS command line).

- If you are familiar with vi, you may find useful to download and install
  ``MSYS vim`` (this is done in a similar way to GCC 4).
  This is strictly optional and mostly helpful to edit configuration files
  from within MSYS.

- Run MSYS (Start/Programs/MinGW/MSYS/MSYS) and check the installation
  by verifying that the proper version of GCC is found:

    .. code-block:: bash

        gcc --version

  You may also decide to change the location of your home directory by
  adding a line at the beginning of msys.bat, that would look like
  ``set HOME=C:\My\Home\For\MinGW`` (you can also set a global ``HOME``
  environment variable within Windows, but this could affect more programs).

- If you do not have them already, install the latest versions of
  `Python 2.x <http://www.python.org/download/windows>`__ and
  corresponding `Numpy <http://sourceforge.net/projects/numpy/files/>`__
  then `SciPy <http://sourceforge.net/projects/scipy/files/>`__
  packages (simply use the executable installers).

- Ensure that the Python installation directory and its ``Scripts`` sub-directory
  are in your system path. This may be done by
  modifying the global ``PATH`` Windows environment variables, or by creating a ``.profile`` file in
  your MinGW home, containing the line
  ``export PATH=$PATH:/c/Python26:/c/Python26/Scripts``
  (for Python 2.6).

- Install a ``BLAS`` library. Note that although the following instructions
  will give you a generic way to build your own library, there may exist
  better (more optimized) versions of BLAS available for your system, but
  these have not been tested for Windows at this time.
  To build BLAS, download the latest version of `LAPACK <http://www.netlib.org/lapack/>`__
  (typically lapack.tgz), then issue the following commands in MSYS
  (for LAPACK 3.2.1):
  
    .. code-block:: bash

        tar zxvf lapack.tgz
        cd lapack-3.2.1
        gfortran -shared -O3 -o libblas.dll BLAS/SRC/*.f
        cp libblas.dll /mingw/lib
        mv libblas.dll /mingw/bin

- Edit (or create) your ``$HOME/.theanorc`` and add the following section:

    .. code-block:: bash

        [blas]
        ldflags = -lblas

- Install `Mercurial <http://mercurial.selenic.com/downloads/>`__
  (you can use the regular Windows release, you do not need TortoiseHg).

- In order to run Theano's test-suite, you will need `nose
  <http://somethingaboutorange.com/mrl/projects/nose>`__.
  After unpacking its source code, you can build and install it from within
  the code directory by:

    .. code-block:: bash

        python setup.py install

- Install Theano using the above :ref:`install_bleeding_edge` installation instructions
  (using ``easy_install`` will require additional packages and has not been
  tested yet, while the latest official Theano release is also untested at this
  time).
  In particular, do not forget to make the Theano package accessible from
  Python, e.g. by adding to your ``.profile`` a line like
  ``export PYTHONPATH=PYTHONPATH:$HOME/Theano``.

- Please note that at this time, some tests (launched using ``nosetests``) are
  still failing under Windows: we are working on fixing them.
  It may also happen that many tests may fail while running the test-suite,
  due to insufficient memory resources (in which case you will probably get an
  error of the type ``"Not enough storage is available to
  process this command"``): one workaround is to run nosetests
  multiple times under individual subdirectories.
  

Generating the documentation
----------------------------

You can read the latest HTML documentation `here
<http://deeplearning.net/software/theano>`__.
You can download the latest PDF documentation `here
<http://deeplearning.net/software/theano/theano.pdf>`__.

We recommend you look at the documentation on the website, since it
will be more current than the documentation included with the package.

If you really wish to build the documentation yourself, you will need
epydoc and sphinx, as described above. Issue the following command::

    python ./doc/scripts/docgen.py

Documentation is built into ``html/``.
The PDF of the documentation is ``html/theano.pdf``.


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