
.. _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)
        Including the development package(python-dev or python-devel on most OS)

    g++, python-dev
        Highly recommended, to compile generated C code.
	We currently compile when we import theano. This could be moved to when we compile c code
	to allow using theano without c code generation. If someone has the time to do it,
	it would be welcome. We still would recommend to have them to have faster time.

    `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:

    `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.	
    `nvidia cuda driver and sdk <http://developer.nvidia.com/object/gpucomputing.html>`_
    	Needed if you want to use the GPU. Only nvidia gpu and float32 dtype supported for now.

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

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

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

.. code-block:: bash

    cd Theano
    THEANO_FLAGS=warn.ignore_bug_before=all nosetests #execute all the tests


THEANO_FLAGS is an environment variable that define Theano flags (:ref:`libdoc_config`).
For Windows user, you can remove it or see the doc to know how to configure them differently.

All tests should pass except the test marked as KnownFailureTest. If some test 
fails on your machine, you are encouraged to tell us what went wrong on the 
``theano-users@googlegroups.com`` mailing list.

.. note::

    `warn.ignore_bug_before=all` removes warnings that you don't need to see here.
    It is also recommended for a new user to set this flag to a different value 
    into their .theanorc file.
    See :attr:`config.warn.ignore_bug_before` for more details.

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.


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). You may also
  need to add

    .. code-block:: bash

      [gcc]
      cxxflags = -L/opt/local/lib

  to ``~/.theanorc``.

- 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 V1 (bigger install, but simpler instructions + tentative GPU instructions)
----------------------------------------------------------------------------------

- Install `Python(x,y) <http://www.pythonxy.com>`_. It is a single installation
  file that contains additional packages like Numpy, Scipy, IPython, Matplotlib,
  MinGW, Nose, etc. Note that this implies you do not already have a Python
  installation (if you do have one, then you will need to either remove it first,
  or install those additional packages manually as described in the V2 instructions).

- Install Mercurial. You can download it
  `here <http://mercurial.selenic.com/downloads>`_. You may get either the command
  line Windows version or the TortoiseHG GUI version: it does not matter as
  far as installing Theano is concerned.

- Start a shell (hit the Start button and run the ``cmd`` command) and navigate to
  the directory where you want to install Theano (it is ok to just stay in the
  default directory, which should be your user profile directory). Then download
  Theano with:

    .. code-block:: bash

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

- Add (or edit) the PYTHONPATH environment variable (into Control
  Panel / System / Advanced / Environment Variables), so that it contains
  the full installation directory of Theano. Restart a shell (``cmd``) to verify
  that it works:

    .. code-block:: none

        C:\Users\login>echo %PYTHONPATH%
        C:\Users\login\Theano
        
- Create a new ``.theanorc`` text file (or ``.theanorc.txt``, which is easier
  to create under Windows) in your user profile directory, containing the following
  two lines:
 
    .. code-block:: bash

      [blas]
      ldflags =

- You are now ready to run Theano.
  It will use NumPy for dot products, which is still pretty fast (see below for
  optional instructions on how to compile your own BLAS library).
  To test that theano correctly reads your configuration file, run Python
  (e.g. by just typing ``python`` in a shell) and run the following code:

  .. code-block:: python

      import theano
      print theano.config.blas.ldflags

  This should print the same content as in your config file, i.e. nothing
  (if your config file was not read properly, it would print ``-lblas``, and
  trying to compile any Theano function would result in a compilation error
  due to the system being unable to find ``blas.dll``).

Windows V1.5 (optional follow-up to V1 instructions)
----------------------------------------------------

- If you want a faster and/or multithreaded BLAS library, you can
  compile GotoBLAS2. We did not try to compile ATLAS because we read that
  it is slower than Goto and more difficult to compile (especially on
  Windows).
  GotoBLAS2 can be downloaded
  `here <http://www.tacc.utexas.edu/tacc-projects/gotoblas2/downloads>`_
  after registering on the website (we tested v1.13).
  To compile it, you also need to install MSYS and Perl (for instance
  ActivePerl).
  The GotoBLAS makefiles actually expect a full UNIX environment (like
  Cygwin) but the BLAS compilation seems to work with only MSYS and Perl.
  The LAPACK compilation fails, but is not needed anyways.

  (WORK-IN-PROGRESS, TO BE CONTINUED)

  Compilation steps:

  a) Unpack GotoBLAS2 (using `7-zip <http://www.7-zip.org/>`_ or the
     MSYS tar command).

  b) open MSYS, change directory to GotoBLAS2 (cd command)

  c) type "quickbuild.win32 1>log.txt 2>err.txt"
     The compilation takes a few minutes. Afterwards, you will find
     lots of error messages in the err.txt file, but you
     should also find a libgoto2.dll file in the exports folder.

  d) Copy libgoto2.dll from the exports folder to mingw\bin and mingw\lib.

  e) Modify the .theanorc file: ldflags = -lgoto2
     This setting can also be changed in Python for testing purposes:
     theano.config.blas.ldflags = ...

- (Optional). To test the BLAS performance, you can run the script check_blas.py.
  For comparison I also downloaded and compiled the unoptimized standard
  BLAS. The results were the following (Intel Core2 Duo 1.86 GHz):

         Standard BLAS: 166 sec (unoptimized, 1 thread)
         NumPy: 48 sec (1 thread)
         Goto2: 16 sec (2 threads)

  Conclusions:
  a) The unoptimized standard BLAS is very slow. Don't use it.
  b) The Windows binaries of NumPy were compiled with ATLAS and are surprisingly fast.
  c) GotoBLAS is even faster, in particular if you have several kernels.

- (Optional) Gpu on Windows. Not sur it work! Can you report success/error on the `theano-users <http://groups.google.com/group/theano-users>`_ mailing list?

  Those are indication for 32 bits version of python, the one that come with pythonxy is 32 bits.

  Space or non ascii caracter are not always supported in path. Python support 
  them, so your configuration file path can contain them. 
  nvcc(at least version 3.1) don't support them well. If your USERPROFILE 
  directory contain those caractere, you must add in your configuration file:

    .. code-block:: bash

      [global]
      base_compiledir=PATH_TO_A_DIRECTORY_WITHOUT_THOSE_CARACTERE

  You also need to add in the configuration file those line:

    .. code-block:: bash

      [cuda]
      nvccflags=-LC:\Python26\libs

  Then
  
  1) Install cuda driver(32 bits on 32 bits Windows, idem for 64 bits).
  
  2) Install cuda toolkit 32 bits(even if you computer is 64 bits, 
     must match the python installation version)
  
  3) Install cuda sdk 32 bits
  
  4) Test some pre-compiled example of the sdk

  5) Download Visual Studio 2008 Express(free, VS2010 not supported by nvcc 3.1,
     VS2005, not available for download, but supported by nvcc, the non free version should work too)

  6) Follow the instruction in the GettingStartedWindows.pdf file from cuda web 
     site to compile cuda code with VS2008. If that don't work, you won't be 
     able to compile gpu code with theano.

  7) Put into you PATH environment variable the directory where cl.exe is. 
     In my case it is: C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin

  8) Make sure the theano folder is in your PYTHONPATH environment variable.

  9) Then in theano do: import theano.sandbox.cuda

     That will print some error if their is an error to compile the first cuda file.

  10) Then run the theano cuda test file. In Windows command line (cmd.exe), 
      run the program nosetests inside the theano repository. 
      nosetests is installed by pythonxy.

Windows V2(smaller install, but longer instruction)
---------------------------------------------------

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
