Note
If you are a member of LISA Labo, have a look at LISA Labo specific instructions for lab-specific installation instructions.
In order to use Theano, the following libraries and software will need to be installed:
- Linux, OS-X or Windows operating system
- We develop mainly on 64-bit Linux machines. 32-bit architectures are not well-tested.
python >= 2.5 (2.4 should be supported as well)
- numpy >= 1.2
- Earlier versions have memory leaks.
- SciPy
- 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:
If you are a developer of Theano, then check out the Developer 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:
hg clone http://hg.assembla.com/theano Theano
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:
ln -s Theano/theano <someplace on your PYTHONPATH>/theano
To modify the environment variable PYTHONPATH in bash, you may do this:
export PYTHONPATH=<path to Theano's parent dir>/Theano:$PYTHONPATH
In csh:
setenv PYTHONPATH <path to Theano's parent dir>/Theano:$PYTHONPATH
Theano currently depends on having a BLAS library to link against. The default is to use the blas installation information in numpy: numpy.distutils.__config__.show, but if numpy is not configured [correctly] for using a fast BLAS, you should tell Theano which BLAS to use via the THEANO_FLAGS environment variable, or a .theanorc file.
The .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:
# other stuff can go here
[blas]
ldflags = -lf77blas -latlas -lgfortran #put your flags here
# other stuff can go here
If you prefer to use an environment variable, type something like this: export THEANO_FLAGS="blas.ldflags=<gcc linker flags>" so maybe export THEANO_FLAGS="blas.ldflags=-lf77blas -latlas -lgfortran" might work for you.
For more information on the formatting of ~/.theanorc and the configuration options that you can put there, see config – Theano Configuration.
Once you have completed these steps, you should run the theano test suite like this:
cd Theano
nosetests #execute all the tests
All tests should pass. If some test fails on your machine, you are encouraged to tell us what went wrong on the theano-users@googlegroups.com mailing list.
To update your library to the latest revision, change directory (cd) to your Theano folder and execute the following command:
hg pull -u
You should update frequently, bugs are fixed on a very regular basis.
If the above required libraries are not already installed on your Mac, one option is first, to install MacPorts.
Then, in order to install one or more of the required libraries, use “port install”, e.g. as follows:
$ sudo port install gcc44 py25-scipy mercurial python_selectThis will install all the required theano dependencies. Note that compiling gcc takes significant time (hours)! SciPy depends on ATLAS (a good BLAS implementation) and numpy, so these will be installed for you automatically.
You might have some old versions of gcc, SciPy, numpy, Python installed on your system, perhaps via XCode. It is a good idea to use either the MacPorts version of everything or some other set of compatible versions (provided by fink, or by XCode). The advantages of MacPorts are the transparency with which everything can be installed and the fact that packages are updated quite frequently.
In order to use the MacPorts version of python, you might need to explicitly select it with sudo python_select python25. The reason this is necessary is because you might have an Apple-provided python (via, for example, an XCode installation). After performing this step, you should check that the symbolic link provided by which python points to the MacPorts python. For instance, on Snow Leopard with the latest MacPorts, the output of which python is /opt/local/bin/python and this symbolic link points to /opt/local/bin/python2.5. When executing sudo python_select python26-apple (which you should not do), the link points to /usr/bin/python2.6.
Once this is fixed, please check that the scipy module that is imported in Python is the right one (and is a recent one). For instance, import scipy followed by print scipy.version and print scipy.__path__ should result in a version number of at least 0.7.0 and a path that starts with /opt/local (the path where MacPorts installs its packages). If this is not the case, then you might have some old installation of scipy in your PYTHONPATH so you should edit PYTHONPATH accordingly.
Please follow the same procedure with numpy.
Put export PYTHONPATH=/opt/local/lib/python2.5/site-packages:$PYTHONPATH in your .bashrc in order to include your MacPorts Python packages (numpy, scipy) in Python’s path.
Make sure that the gcc version that you have installed on your system is up-to-date (at the very least 3.4, but 4.x is better). If you have an old version of XCode lying around, chances are that your gcc install is old. You should also check which gcc: if it says /usr/bin/gcc then you should install gcc_select from MacPorts (sudo port install gcc_select) and use the MacPorts-provided gcc. Use gcc_select -l to see which gcc installs you have on the system. Then execute sudo gcc_select mp-gcc44 to create a symlink that points to the correct (MacPorts) gcc (version 4.4 in this case).
This is covered in the MacPorts installation process, but make sure that your PATH environmental variable contains /opt/local/bin and /opt/local/sbin before any other paths (to ensure that the python and gcc binaries that you installed with MacPorts are visible first).
Likewise, you need to export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH if this is not the case already (so that we link to the correct libraries).
An obscure Bus error can sometimes be caused when linking Theano-generated object files against the framework library in Leopard. For this reason, we’ve disabled linking with -framework Python, since on most configurations this solves the Bus error problem. If this default configuration causes problems with your Python/theano installation and you think that linking with -framework Python might help, then either set THEANO_FLAGS=cmodule.mac_framework_link or edit your ~/.theanorc to contain
[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).
Running Theano under Windows is currently achieved by using the MinGW port of the GCC compiler. It could probably also run with Cygwin, but this has not been tested yet.
From the MinGW files, download the latest version of the Automated MinGW Installer and install it (keeping default options).
From the 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, 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 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 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:
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 and corresponding Numpy then SciPy 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 (typically lapack.tgz), then issue the following commands in MSYS (for LAPACK 3.2.1):
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
Install Mercurial (you can use the regular Windows release, you do not need TortoiseHg).
In order to run Theano’s test-suite, you will need nose. After unpacking its source code, you can build and install it from within the code directory by:
python setup.py install
Install Theano using the above Getting the code 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.
You can read the latest HTML documentation here. You can download the latest PDF documentation here.
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.