
.. _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. Note that GPU computing does not work yet under
        Windows.

    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.

    `Mercurial <http://mercurial.selenic.com/>`_
        To download bleeding-edge versions of Theano.

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

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

.. note::

    The tests should be run with the ``THEANO_FLAGS``(defined later)
    ``device=cpu`` (default). Otherwise, it will generate false errors.

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

Bleeding-edge (developer) install instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are a developer of Theano, then check out the :ref:`dev_start_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://mercurial.selenic.com/>`__:

.. code-block:: bash

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

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 Mercurial). Using ``develop`` mode is
preferable to ``install`` as any modifications you make in the checkout
directory (or changes you pull with Mercurial) 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

    hg pull -u

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 Mercurial checkout directory by typing

.. code-block:: bash

    nosetests

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

.. note::

    The tests should be run with the ``THEANO_FLAGS`` ``device=cpu`` (default).
    Otherwise, it will generate false errors.

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.

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


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 py26-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 python26``. 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.6``. 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.6/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:: cfg

      [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:: cfg

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

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 Mercurial, which you can get
`here <http://mercurial.selenic.com/downloads>`__.
You may install either the command
line Windows version or the TortoiseHG GUI version: it does not matter as
far as installing Theano is concerned.

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

        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 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``, which is easier
  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 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').

- You should be able to run the test-suite by executing ``nosetests`` within
  the Theano installation directory (if you installed Nose manually as described
  above, this may only work in a MinGW shell).
  Please note that at this time, the test suite may be broken under Windows.
  In particular, 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.

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

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>`__
after registering on the website (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 from the
  `MinGW files <http://sourceforge.net/projects/mingw/>`_ (click
  "View all files", and make sure you do not mix it up with
  mingw-get-inst).

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

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

At this point, GPU computing does not work under Windows. The current main
issue is that the compilation commands used under Linux / MacOS to create
and use a CUDA-based shared library with the nvcc compiler do not work with
Windows DLLs. If anyone can figure out the proper compilation steps for
Windows, please let us know on the `theano-dev`_ mailing list.

Instructions below should at least get you started so you can reproduce the
above-mentioned issue.
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 (at least version 3.1) does not.
If your ``USERPROFILE`` directory (the one you get into when you run ``cmd``)
contains such characters, you must edit your Theano configuration file to
use a compilation directory located somewhere else:

    .. code-block:: cfg

      [global]
      base_compiledir=path_to_a_directory_without_such_characters

Then

  1) Install CUDA driver (32-bit on 32-bit Windows, idem for 64-bit).

  2) Install CUDA toolkit 32-bit (even if you computer is 64-bit,
     must match the Python installation version).

  3) Install CUDA SDK 32-bit.

  4) Test some pre-compiled example of the sdk.

  5) Download Visual Studio 2008 Express (free, VS2010 not supported by nvcc 3.1,
     VS2005 is 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 the CUDA web
     site to compile CUDA code with VS2008. If that does not work, you will
     not be able to compile GPU code with Theano.

  7) Edit your Theano configuration file to add lines like the following
     (make sure these paths match your own specific installation):

     .. code-block:: cfg

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

        [nvcc]
        compiler_bindir=C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin

  8) In Python do: ``import theano.sandbox.cuda``. This will compile the
     first CUDA file, and no error should occur.

  9) Then run the Theano CUDA test files with nosetests from the
     ``theano/sandbox/cuda/tests`` subdirectory. In the current version of
     Theano, this should fail with an error like:

     .. code-block:: bash

        NVCC: nvcc fatal: Don't know what to do with
            'C:/CUDA/compile/tmpmkgqx6/../cuda_ndarray/cuda_ndarray.pyd'


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
