
.. _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 (MacOS and Windows users should refer to platform-specific
instructions below for detailed installation steps):

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

    Python_ >= 2.4
        The development package (``python-dev`` or ``python-devel``
        on most Linux distributions) is recommended (see just below).

    ``g++``, ``python-dev``
        Not technically required but *highly* recommended, in order to compile
        generated C code. Theano `can` fall back on a NumPy-based Python execution
        model, but a C compiler allows for vastly faster execution.

    `NumPy <http://numpy.scipy.org/>`_ >= 1.3.0
        Earlier versions have memory leaks.

    `SciPy <http://scipy.org>`_
        Only currently required for sparse matrix and special functions
        support, but *highly* recommended. We recommend SciPy
        >=0.7 if you are using sparse matrices, because ``scipy.sparse``
        is buggy in 0.6 (the ``scipy.csc_matrix`` version of ``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). Mac OS X comes with the `Accelerate
        framework`_ built in, and various options exist for Windows (see
        below).

.. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
.. _Accelerate framework: http://developer.apple.com/performance/accelerateframework.html
.. _Python: http://www.python.org/

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/>`_
        For building the documentation. LaTeX_ and dvipng_ are also necessary
        for math to show up as images.

    `Git <http://git-scm.com>`_
        To download bleeding-edge versions of Theano.

    `pydot <https://code.google.com/p/pydot/>`_
        To be able to make picture of Theano computation graph.

    `NVIDIA CUDA drivers and SDK`_
        Required for GPU code generation/execution. Only NVIDIA GPUs using
        32-bit floating point numbers are currently supported.

.. _LaTeX: http://www.latex-project.org/
.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
.. _NVIDIA CUDA drivers and SDK: http://developer.nvidia.com/object/gpucomputing.html

Linux
-----

.. _linux_basic:

Alternative installation on Ubuntu with PPA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Benjamin J. McCann provides `installation documentation <http://www.benmccann.com/dev-blog/installing-cuda-and-theano/>`_ for Ubuntu 11.04 with CUDA 4.0 PPA.

Basic user install instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The easiest way to obtain the released version of Theano is from PyPI using
pip_ (a replacement for easy_install_ provided by setuptools_/distribute_)
by typing

.. code-block:: bash

    pip install Theano

You may need to add ``sudo``  before this command to install into your
system's ``site-packages`` directory. If you do not have administrator access
to your machine, you can install to an alternate prefix using

.. code-block:: bash

    pip install Theano --install-option='--prefix=YOURPREFIX'

e.g. using ``--install-option='--prefix=~/.local'`` on Python 2.4 would
install Theano into ``.local/lib/python2.4/site-packages`` inside your home
directory on Mac OS X or Unix/Linux (this ``site-packages`` directory must be
listed in your ``PYTHONPATH`` environment variable; for Python 2.6 and later,
``~/.local`` is
automatically searched and does *not* need to be explicitly included in
``PYTHONPATH``, see :ref:`config_pythonpath` for instructions).

Alternatively you can use virtualenv_ to create an isolated ``site-packages``
directory; see the `virtualenv documentation`_ for details.

.. note::

    Theano *can* be installed with easy_install_, however we recommend pip_ as
    a long-standing bug in ``easy_install`` prevents ``theano.test()`` from
    running the Theano test suite; ``pip`` offers many other benefits over
    ``easy_install`` such as more intelligent dependency management, better
    error messages and a ``pip uninstall`` command for easily removing
    packages.

    If you do not have ``pip`` installed but do have ``easy_install``, you can
    get ``pip`` by simply typing ``easy_install pip``.

.. _distribute: http://packages.python.org/distribute/
.. _setuptools: http://pypi.python.org/pypi/setuptools
.. _easy_install: http://packages.python.org/distribute/easy_install.html
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _virtualenv documentation: http://virtualenv.openplans.org/
.. _pip: http://pypi.python.org/pypi/pip

.. _install_bleeding_edge:

With rpm package
~~~~~~~~~~~~~~~~

A contributor made rpm package for Mandriva_ 2010.2 of Theano 0.3.1.

.. _Mandriva: http://mib.pianetalinux.org/mib/quick/basic-rpms/mib-rpms/975-theano-031

Bleeding-edge install instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

If you want the bleeding-edge without developing the code you can use pip for
this with the command line below. Note that it will also try to download and
upgrade Theano's dependencies (like numpy and scipy). If you do not wish to do
so, add the ``--no-deps`` switch to it.

.. code-block:: bash

    pip install --upgrade git+git://github.com/Theano/Theano.git

or (if you want to install to a custom directory):

.. code-block:: bash

    pip install --upgrade git+git://github.com/Theano/Theano.git --install-option='--prefix=YOURPREFIX'

The following are general instructions that will set you up with the
bleeding-edge version of Theano and allow you to hack it. First,
get the code using `Git <http://git-scm.com>`__:

.. code-block:: bash

    git clone git://github.com/Theano/Theano.git

From here, the easiest way to get started is

.. code-block:: bash

    cd Theano
    python setup.py develop

This will install a ``.pth`` file in your ``site-packages`` directory that
tells Python where to look for your Theano installation (i.e. in the
directory your just checked out of Github). Using ``develop`` mode is
preferable to ``install`` as any modifications you make in the checkout
directory (or changes you pull with Git) will be automatically reflected
in the "installed" version without re-running ``python setup.py install``.

If you do not have permission to modify your ``site-packages`` directory you
can specify an alternative installation prefix using

.. code-block:: bash

    python setup.py develop --prefix=YOURPREFIX

A common choice is ``~/.local`` which is automatically searched for Python >=
2.6; for earlier Python versions and other installation prefixes, the prefix
specified must contain ``lib/pythonA.B/site-packages``, where ``A.B`` is e.g.
2.5, and this ``site-packages`` directory must be listed in ``PYTHONPATH``.

An alternative, perhaps simpler way of creating and using an isolated
``site-packages`` is to use virtualenv_; see the `virtualenv documentation`_
for details. If you find yourself using virtualenv frequently you may find the
virtualenvwrapper_ package useful for switching between them.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _virtualenv documentation: http://virtualenv.openplans.org/
.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/

.. _config_pythonpath:

Configuring ``PYTHONPATH``
##########################

If ``import theano`` does not work in Python, you may need modify the
environment variable ``PYTHONPATH`` accordingly.
In bash, you may do this:

.. code-block:: bash

    export PYTHONPATH=<new location to add>:$PYTHONPATH

In csh:

.. code-block:: csh

    setenv PYTHONPATH <new location to add>:$PYTHONPATH

To make this change stick you will usually need to add the above command to
your shell's startup script, i.e. ``~/.bashrc`` or ``~/.cshrc``.
Consult your shell's documentation for details.

Updating
########

To update your library to the latest revision, change directory (``cd``)
to your ``Theano`` folder and execute the following command:

.. code-block:: bash

    git pull

You should update frequently, bugs are fixed on a very regular basis.


Testing your installation
~~~~~~~~~~~~~~~~~~~~~~~~~

Once you have installed Theano, you should run the test suite. At
a Python (or IPython) interpreter,

.. code-block:: python

    >>> import theano
    >>> theano.test()

You can also run them in-place from the Git checkout directory by typing

.. code-block:: bash

    nosetests

.. note::

    The tests should be run with the configuration option :attr:`~config.device`
    set to ``cpu`` (default). If you need to change this value,
    you can do that by setting the :envvar:`THEANO_FLAGS` environment variable,
    by prefixing the ``nosetests`` command with ``THEANO_FLAGS=device=cpu``.
    If you have a GPU, it will automatically be used to run GPU-related tests.

    If you want GPU-related tests to run on a specific GPU device, and not
    the default one, you should use :attr:`~config.init_gpu_device`.
    For instance: ``THEANO_FLAGS=device=cpu,init_gpu_device=gpu1``.

    See :ref:`libdoc_config` for more information on how to change these
    configuration options.

All tests should pass except those 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.


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 did not 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
environment variable :envvar:`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:: cfg

    # 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 against which NumPy was built. This does not work in the case NumPy was
compiled with a static library (e.g. ATLAS is compiled by default only as a
static library).

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
(against which Theano links) does not 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 use 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. Your ATLAS installation might need to be modified
    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.


MacOS
-----

There are various ways to install Theano dependencies on a Mac.
Here we describe the process in details using MacPorts, but if you did
it differently and it worked, please let us know the details on the
`theano-users`_ mailing-list, so that we can add alternate instructions
here.

MacPorts
~~~~~~~~

Using `MacPorts <http://www.macports.org/>`__ to install all required
Theano dependencies is easy, but be aware that it will take a long time
(a few hours) to build and install everything.

- MacPorts requires installing XCode first (which can be found in the
  Mac App Store), if you do not have it already.

- Download and install `MacPorts <http://www.macports.org/>`__, then
  ensure its package list is up-to-date with ``sudo port selfupdate``.

- 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 py27-numpy +atlas py27-scipy +atlas py27-pip

  This will install all the required Theano dependencies. gcc will
  be automatically installed (since it is a SciPy dependency), but be
  aware that it takes a long time to compile (hours)!
  Having NumPy and SciPy linked with ATLAS (an optimized BLAS
  implementation) is not mandatory, but recommended if you care about
  performance.

- You might have some different 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
  (e.g. provided by Xcode or Fink). The advantages of MacPorts are the
  transparency with which everything can be installed and the fact that
  packages are updated quite frequently. The following steps describe how to
  make sure you are using the MacPorts version of these packages.

- In order to use the MacPorts version of Python, you will probably
  need to explicitly select it with ``sudo port select python python27``. The
  reason this is necessary is because you may 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 MacOS X Lion with MacPorts 2.0.3,
  the output of ``which python`` is ``/opt/local/bin/python`` and this symbolic
  link points to ``/opt/local/bin/python2.7``. When executing ``sudo
  port select python python27-apple`` (which you should **not** do), the link
  points to ``/usr/bin/python2.7``.

- Similarly, make sure that you are using the MacPorts-provided gcc:
  use ``sudo port select gcc`` to see which gcc installs you have on the
  system. Then execute for instance ``sudo port select gcc mp-gcc44``
  to create a symlink that points to the correct (MacPorts) gcc (version 4.4
  in this case).

- At this point, if you have not done so already, it may be a good idea to
  close and restart your terminal, to make sure all configuration changes
  are properly taken into account.

- Afterwards, 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``.

- This is covered in the MacPorts installation process, but make sure that
  your ``PATH`` environment 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).

- MacPorts does not create automatically ``nosetests`` and ``pip`` symlinks
  pointing to the MacPorts version, so you can add them yourself with

    .. code-block:: bash

        $ sudo ln -s /opt/local/bin/nosetests-2.7 /opt/local/bin/nosetests
        $ sudo ln -s /opt/local/bin/pip-2.7 /opt/local/bin/pip

- At this point you are ready to install Theano with

    .. code-block:: bash

        $ sudo pip install Theano

  And if you are in no hurry, you can run its test-suite with

    .. code-block:: bash

        $ python -c "import theano; theano.test()"


Troubleshooting MacOS issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Although the above steps should be enough, running Theano on a Mac may
sometimes cause unexpected crashes, typically due to multiple versions of
Python or other system libraries. If you encounter such problems, you may
try the following.

- You can ensure MacPorts shared libraries are given priority at run-time
  with ``export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH``. In order
  to do the same at compile time, you can add to your ``~/.theanorc``:

    .. code-block:: cfg

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

- An obscure ``Bus error`` can sometimes be caused when linking
  Theano-generated object files against the ``framework`` library in Leopard.
  For this reason, we have 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
  the :envvar:`THEANO_FLAGS` environment variable with
  ``THEANO_FLAGS=cmodule.mac_framework_link`` or edit your ``~/.theanorc`` to
  contain

    .. code-block:: cfg

      [cmodule]
      mac_framework_link=True

- More generally, to investigate libraries issues, you can use the ``otool -L``
  command on ``.so`` files found under your ``~/.theano`` directory. This will
  list shared libraries dependencies, and may help identify incompatibilities.

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,
alternate installation steps, GPU instructions, 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
-------

Installing Dependencies
~~~~~~~~~~~~~~~~~~~~~~~

If neither Python nor MinGW is installed on your computer, the easiest way to
install most dependencies is to 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.
You can keep the default install options, except that the installation
directory should not contain any blank space (in particular, do not install it
into ``C:\Program Files``).

If instead you already have either Python or MinGW installed, it is safer to
install components individually to avoid conflicts. Note that it should be
possible to run Theano with `Cygwin <http://www.cygwin.com/>`__ instead of
MinGW, but this has not been tested yet. In order to manually install the same
components as in Python(x,y) that are required by Theano, follow these steps:

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest version of the ``Automated MinGW Installer``
  (``mingw-get-inst``) and install it with all optional components (although
  you probably do not need them all: if you feel like figuring out exactly
  which ones are required, let us know!).

- It is recommended to set your MinGW home to be the same as your Windows home
  directory. This will avoid inconsistent behavior between running Theano
  in a Windows command prompt vs. a MinGW shell. One way to do this without
  setting a global Windows ``HOME`` environment variable (which may affect
  other programs) is to edit your ``msys.bat`` file (found e.g. under
  ``C:\MinGW\msys\1.0``) and add the following line at the beginning (note
  that you may need to use e.g. Wordpad to edit this file, since Notepad gets
  confused by Unix-style line breaks):

    .. code-block:: bash

        set HOME=%USERPROFILE%

- 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). Note that we experienced
  issues with the 64 bit version of Python, and thus recommend using the 32 bit
  version instead (if you managed to get Theano to work with 64 bit Python under
  Windows, please let us know!).

- 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 a line like
  ``export PATH=$PATH:/c/Python26:/c/Python26/Scripts`` (note that the latter
  will work only when you run Theano from a MinGW shell).

- In order to run Theano's test-suite, you will need `nose
  <http://somethingaboutorange.com/mrl/projects/nose>`__.
  After unpacking its source code (you may use `7-zip
  <http://www.7-zip.org/>`__), you can build and install it from within
  its code directory by running the following command (either from a Windows
  command prompot or a MinGW shell):

    .. code-block:: bash

        python setup.py install

At this point, whether you installed Python(x,y) or individual components, you
should have MinGW, Python, Numpy, Scipy and Nose installed.
In order to download Theano you will also need Git, which you can get
`here <http://git-scm.com/download>`__ (download the latest version of the
"Full installer for official Git" from the ``msysgit`` download page).

Installing Theano
~~~~~~~~~~~~~~~~~

It should be possible to install Theano with ``pip`` as described in
:ref:`linux_basic`, but this has not been tested yet under Windows. We describe
here instructions to use the latest code repository version (bleeding-edge).
Command lines listed below are assumed to be run in a Windows prompt
(click ``Start`` and type the ``cmd`` command), and may need to be adapted if
used within a MinGW Shell (not available if you only installed Python(x,y)).

- Navigate into the directory you want Theano to be installed in, and download
  it with

    .. code-block:: bash

        git clone git://github.com/Theano/Theano.git

- 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 prompt 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``, whichever is easier
  for you to create under Windows) in your user profile directory (the directory you
  are into when you start a new command prompt with ``cmd``), containing the
  following two lines:

    .. code-block:: cfg

      [blas]
      ldflags =

  You do not need to do the following now, because it is not usually needed, but if
  later on, when running Theano, you see an error message that looks like:
  *error: 'assert' was not declared in this scope*
  then you will have to add another section:

    .. code-block:: cfg

      [gcc]
      cxxflags = -IC:\MinGW\include

- 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 prompt) 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').

Testing your installation
~~~~~~~~~~~~~~~~~~~~~~~~~

Currently, due to memory fragmentation issue in Windows, the
test-suite breaks at some point when using ``nosetests``, with many error
messages looking
like: ``DLL load failed: Not enough storage is available to process this
command``. As a result, you should instead run

    .. code-block:: bash

        python theano/tests/run_tests_in_batch.py

This will run tests in batches of 100, which should avoid memory errors.
Note that this script calls ``nosetests``, which may require being run from
within a MinGW shell if you installed Nose manually as described above.

Editing code in Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You will find a Visual Studio solution file (``Theano.sln``) in the root of
the Theano repository. Note that this project file may not be kept up-to-date
and is not officiallly supported by the core Theano developers: it is provided
for convenience only.
Also, be aware that it will not make Theano use Visual Studio to compile C
files: it is only meant to provide an easy way to edit Theano code within
the Visual Studio editor.

Compiling a faster BLAS
~~~~~~~~~~~~~~~~~~~~~~~

.. note::

   GotoBLAS is no longer maintained and has been released under the BSD
   license. `OpenBLAS
   <https://github.com/xianyi/OpenBLAS>`_ is a new project that
   continues GotoBLAS: it has a better installation process and implements
   additional functions (not currently used by Theano).
   We did not try OpenBLAS on Windows.

If you want a faster and/or multithreaded BLAS library, you can
compile GotoBLAS2 (ATLAS may work too, but was not tested, and is
usually reported to be slower and more difficult to compile -- especially
on Windows).
GotoBLAS2 can be downloaded
`here <http://www.tacc.utexas.edu/tacc-projects/gotoblas2/downloads>`__
(we tested v1.13).
To compile it, you will also need MSYS and Perl (installation steps are
described below).
The GotoBLAS makefiles actually expect a full UNIX environment (like
Cygwin) but the BLAS compilation seems to work with only MSYS and Perl
(LAPACK compilation fails, but Theano does not need it).

If you installed MinGW manually as described above, you should already
have MSYS included in your MinGW install, and should be able to start a
shell (Start / MinGW / MinGW Shell), in which case you can skip the MSYS
installation.
If instead you installed Python(x,y), you will need to install MSYS on
top of the MinGW installation included within Python(x,y), as follows:

- Download the `mingw-get command-line installer binary
  <http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get/>`_.

- Unpack it into your ``pythonxy\mingw`` directory.

- In a prompt (``cmd``), install MSYS with

    .. code-block:: bash

        mingw-get install msys-base

- Edit ``pythonxy\mingw\msys\1.0\msys.bat`` (e.g. in Wordpad) and add as first
  line ``set HOME=%USERPROFILE%``. Then create an easily accessible shortcut
  (e.g. on your desktop) to this file, run it and within the MSYS
  console, run the MSYS post-install script:

    .. code-block:: bash

        /postinstall/pi.sh

  It will ask for your MinGW installation directory (e.g.
  ``c:/pythonxy/mingw``).

Once you have a working MinGW/MSYS shell environment, you can go on as
follows:

  a) Download `ActivePerl <http://www.activestate.com/activeperl/downloads>`_ and
     install it (other Perl interpreters should also work, but were not
     tested). In a MSYS shell, type ``perl --version`` just to make sure the Perl
     executable is found automatically. If this is not the case, you may need to
     restart your MSYS shell, or even restart your computer if that is not enough.

  b) Unpack GotoBLAS2, either using `7-zip <http://www.7-zip.org/>`__ or in
     a shell with:

    .. code-block:: bash

        tar zxvf /path/to/GotoBLAS2-1.13.tar.gz

  c) In a MSYS shell, go into the GotoBLAS2 directory that was unpacked.

  d) Compile GotoBLAS2 with:

    .. code-block:: bash

      quickbuild.win32 1>log.txt 2>err.txt

    Compilation should take a few minutes. Afterwards, you will probably
    find many error messages in err.txt, but there should be an ``exports``
    folder containing in particular ``libgoto2.dll``.

  e) Copy ``libgoto2.dll`` from the ``exports`` folder to both your ``bin`` and
     ``lib`` subdirectories of your MinGW installation (which may be under
     ``pythonxy\mingw`` if you used Python(x,y)).

  f) Modify your .theanorc (or .theanorc.txt) with ``ldflags = -lgoto2``.
     This setting can also be changed in Python for testing purpose (in which
     case it will remain only for the duration of your Python session):

    .. code-block:: python

        theano.config.blas.ldflags = "-lgoto2"

  g) To test the BLAS performance, you can run the script
     ``theano/misc/check_blas.py``.
     Note that you may control the number of threads used by GotoBLAS2 with
     the ``GOTO_NUM_THREADS`` environment variable (default behavior is to use
     all available cores).
     Here are some performance results on an Intel Core2 Duo 1.86 GHz,
     compared to using Numpy's BLAS or the un-optimized standard BLAS
     (compiled manually from its source code):

         * GotoBLAS2 (2 threads): 16s
         * NumPy (1 thread): 48s
         * Standard BLAS (un-optimized, 1 thread): 166s

     Conclusions:
        * The unoptimized standard BLAS is very slow and should not be used.
        * The Windows binaries of NumPy were compiled with ATLAS and are surprisingly fast.
        * GotoBLAS2 is even faster, in particular if you can use multiple cores.

Using the GPU
~~~~~~~~~~~~~

Currently, GPU support under Windows is still in an experimental state.
The following instructions should allow you to run GPU-enabled Theano code
only within a Visual Studio command prompt.
Those are instructions for the 32-bit version of Python (the one that comes
with Python(x,y) is 32-bit).

Blanks or non ASCII characters are not always supported in paths. Python supports
them, but nvcc may not (for instance version 3.1 does not).
It is thus suggested to manually define a compilation directory without such
characters, by adding to your Theano configuration file:

    .. code-block:: cfg

      [global]
      base_compiledir=path_to_a_directory_without_such_characters

Then

  1) From the CUDA downloads page, download and install:

    a. The Developer Drivers (32-bit on 32-bit Windows, 64-bit on 64-bit
       Windows).

    b. The CUDA Toolkit (32-bit even if your Windows is 64-bit, as it must
       match your Python installation).

    c. The GPU Computing SDK (32-bit as well).

  2) Test some pre-compiled examples of the SDK.

  3) Install Visual C++ (you can find free versions by looking for "Visual
     Studio Express").

  4) Follow instructions from the "CUDA Getting Started Guide" available on
     the NVidia website to compile CUDA code with Visual C++. If that does not
     work, you will probably not be able to compile GPU code with Theano.

  5) Edit your Theano configuration file to add lines like the following
     (make sure these paths match your own specific versions of Python and
     Visual Studio):

     .. code-block:: cfg

        [nvcc]
        flags=-LC:\Python26\libs
        compiler_bindir=C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin

  6) Start a Visual Studio command prompt (found under the "Visual Studio
     Tools" programs folder).
     In Python do: ``import theano.sandbox.cuda``. This will compile the
     first CUDA file, and no error should occur.

  7) To test a simple GPU computation, first set up Theano to use the GPU
     by editing your configuration file:

     .. code-block:: cfg

        [global]
        device = gpu
        floatX = float32

    Then run the ``theano/misc/check_blas.py`` test file.


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
.. _theano-dev: http://groups.google.com/group/theano-dev?pli=1
