.. _install_ubuntu:

Easy Installation of an optimized Theano on Ubuntu
==================================================

These instruction was done for Ubuntu 11.04, 11.10, 12.04, 12.10, 13.04
and 13.10. You can probably do something similar on older computer.

.. note::

    It is possible to have a faster installation of Theano than the one these
    instructions will provide, but this will make the installation more
    complicated and/or may require that you buy software. This is a simple set
    of installation instructions that will leave you with a relatively
    well-optimized version that uses only free software. With more work or by
    investing money (i.e. buying a license to a proprietary BLAS
    implementation), it is possible to gain further performance.

.. note::

   If you are behind a proxy, you must do some extra configuration steps
   before starting the installation. You must set the environment
   variable ``http_proxy`` to the proxy address. Using bash this is
   accomplished with the command
   ``export http_proxy="http://user:pass@my.site:port/"``
   You can also provide the ``--proxy=[user:pass@]url:port`` parameter
   to pip. The ``[user:pass@]`` portion is optional.

.. note::

   We use ``pip`` for 2 reasons. First, it allows "``import module;
   module.test()``" to work correctly. Second, the installation of NumPy
   1.6 or 1.6.1 with ``easy_install`` raises an ImportError at the end of
   the installation. To my knowledge we can ignore this error, but
   this is not completely safe. ``easy_install`` with NumPy 1.5.1 does not
   raise this error.

.. note::

   This page describes how to install Theano for Python 2. If you have
   installed Python 3 on your system, maybe you need to change the
   command pip to ``pip-2.7`` to specify to install it for Python 2, as
   sometimes the pip command refers to the Python 3 version.

   The development version of Theano supports Python 3.3 and
   probably supports Python 3.2, but we do not test on it.


Installation steps
~~~~~~~~~~~~~~~~~~

Ubuntu 11.10/12.04/12.10/13.04/13.10:
 1) ``sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ libopenblas-dev git``
 2) ``sudo pip install Theano``

 If the packages ``libatlas3gf-base`` or ``libatlas-dev`` are already installed, there will be problems as they conflict with ``libopenblas-dev``.
 If you see NumPy errors, the simplest is to remove ``libopenblas-dev`` and its dependency ``libopenblas-base`` like this: ``sudo apt-get remove libopenblas-base``.
 The ideal would be that you remove ``libatlas3gf-base`` and ``libatlas-dev``,
 but you will need to reinstall python-numpy, python-scipy and all other packages that used it.
 OpenBLAS is faster then ATLAS most of the time and it allows to control the number of threads used during the execution.

Ubuntu 11.04:
 1) ``sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ git libatlas3gf-base libatlas-dev``
 2) ``sudo pip install Theano``

.. note::

    If you have error that contain "gfortran" in it, like this one:

        ImportError: ('/home/Nick/.theano/compiledir_Linux-2.6.35-31-generic-x86_64-with-Ubuntu-10.10-maverick--2.6.6/tmpIhWJaI/0c99c52c82f7ddc775109a06ca04b360.so: undefined symbol: _gfortran_st_write_done'

    The problem is probably that NumPy is linked with a different blas
    then then one currently available (probably ATLAS). There is 2
    possible fixes:

    1) Uninstall ATLAS and install OpenBLAS.
    2) Use the Theano flag "blas.ldflags=-lblas -lgfortran"

    1) is better as OpenBLAS is faster then ATLAS and NumPy is
    probably already linked with it. So you won't need any other
    change in Theano files or Theano configuration.


Test the newly installed packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 1) NumPy (~30s): ``python -c "import numpy; numpy.test()"``
 2) SciPy (~1m): ``python -c "import scipy; scipy.test()"``
 3) Theano (~30m): ``python -c "import theano; theano.test()"``

NumPy 1.6.2, 1.7.0 and 1.7.1, have a bug where it marks some ndarrays
as not aligned. Theano does not support unaligned arrays, and raises
an Exception when that happens.  This can cause one test to fail with
an unaligned error with those versions of NumPy. You can ignore that
test error as at worst, your code will crash. If this happens, you can
install another NumPy version to fix this problem. NumPy 1.6.2 is used
in Ubuntu 12.10 and NumPy 1.7.1 is used in Ubuntu 13.04.

Speed test Theano/BLAS
~~~~~~~~~~~~~~~~~~~~~~

It is recommended to test your Theano/BLAS integration. There are many versions
of BLAS that exist and there can be up to 10x speed difference between them.
Also, having Theano link directly against BLAS instead of using NumPy/SciPy as
an intermediate layer reduces the computational overhead. This is
important for BLAS calls to ``ger``, ``gemv`` and small ``gemm`` operations
(automatically called when needed when you use ``dot()``). To run the
Theano/BLAS speed test:

.. code-block:: bash

    python `python -c "import os, theano; print os.path.dirname(theano.__file__)"`/misc/check_blas.py

This will print a table with different versions of BLAS/numbers of
threads on multiple CPUs and GPUs. It will also print some Theano/NumPy
configuration information. Then, it will print the running time of the same
benchmarks for your installation. Try to find a CPU similar to yours in
the table, and check that the single-threaded timings are roughly the same.

Theano should link to a parallel version of Blas and use all cores
when possible. By default it should use all cores. Set the environment
variable "OMP_NUM_THREADS=N" to specify to use N threads.


Updating Theano
~~~~~~~~~~~~~~~

If you followed these installation instructions, you can execute this command
to update only Theano:

.. code-block:: bash

    sudo pip install --upgrade --no-deps theano


If you want to also installed NumPy/SciPy with pip instead of the
system package, you can run this:

.. code-block:: bash

    sudo pip install --upgrade theano


Bleeding edge
~~~~~~~~~~~~~

Do like in the section "Updating Theano", but use
``git+git://github.com/Theano/Theano.git`` instead of ``theano``.


.. _install_ubuntu_gpu:

Manual Openblas instruction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The openblas included in Ubuntu is limited to 2 threads. If you want
to use more cores at the same time, you will need to compile it
yourself. Here is some code that will help you.

.. code-block:: bash

    # remove openblas if you installed it
    sudo apt-get remove libopenblas-base
    # Download the development version of OpenBLAS
    git clone git://github.com/xianyi/OpenBLAS
    cd OpenBLAS
    make FC=gfortran
    sudo make PREFIX=/usr/local/ install
    # Tell Theano to use OpenBLAS.
    # This works only for the current user.
    # Each Theano user on that computer should run that line.
    echo -e "\n[blas]\nldflags = -lopenblas\n" >> ~/.theanorc


Contributed GPU instruction
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Basic configuration for the GPU :ref:`gpu_linux`.

Ubuntu 11.10/12.04 (probably work on 11.04 too):

.. code-block:: bash

   sudo apt-add-repository ppa:ubuntu-x-swat/x-updates
   sudo apt-get update
   sudo apt-get install nvidia-current

Then you need to fetch latest CUDA tool kit (download ubuntu 11.04 32/64bit package)
from `here <http://developer.nvidia.com/cuda-downloads>`_.

For the `run` installed (the only one available for CUDA 5.0 and older), you install it like this:

.. code-block:: bash

    chmod a+x XXX.sh
    sudo ./XXX.sh

Since CUDA 5.5, Nvidia provide a DEB package. If you don't know how to
intall it, just double click on it from the graphical interface. It
should ask if you want to install it.

You must reboot the computer after the driver installation. To test
that it was loaded correctly after the reboot, run the command
`nvidia-smi` from the command line.

You probably need to change the default version of gcc as
`explained by Benjamin J. McCann <http://www.benmccann.com/blog/installing-cuda-and-theano/>`_:




.. code-block:: bash

   sudo apt-get install nvidia-cuda-toolkit g++-4.4 gcc-4.4
   # On Ubuntu 11.10 and 12.04, you probably need to change gcc-4.5 to gcc-4.6 on the next line.
   sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.5 40 --slave /usr/bin/g++ g++ /usr/bin/g++-4.5
   sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.4 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.4
   sudo update-alternatives --config gcc

Test GPU configuration
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    THEANO_FLAGS=floatX=float32,device=gpu python /usr/lib/python2.*/site-packages/theano/misc/check_blas.py

.. note::

   Ubuntu 10.04 LTS: default gcc version 4.4.3. gcc 4.1.2, 4.3.4 availables.

   Ubuntu 11.04: default gcc version 4.5.2. gcc 4.4.5 availables.

   Ubuntu 11.10: default gcc version 4.6.1. gcc 4.4.6 and 4.5.3 availables.

   Ubuntu 12.04 LTS: default gcc version 4.6.3. gcc 4.4.7 and 4.5.3 availables.

   Ubuntu 12.10: default gcc version 4.7.2. gcc 4.4.7, 4.5.4 and 4.6.3 availables.

   Ubuntu 13.10: default gcc version 4.8.1. gcc 4.4.7, 4.6.4 and 4.7.3 availables.
