Skip to content

P
pytensor
提交 c5d3942b authored 作者: Francesco's avatar Francesco 提交者： GitHub
浏览文件
操作

[WIP] Documentation Refactor 2 (#4775)

* Installation documentation refactor * Remove the extra install links from the homepage * Restore pics * Rename css extension to suppress warning * Fix install is not a toctree so is not indexed * Fix multiple labels with same name * Fix stdint.h link * Remove reference to old GCC download instructions * Fix colors * Fix installation instructions * Fix troubleshooting * Fix broken link in dev_start_guide * Prevent doc generation script from using GPUs * Add numpy and scipy max version * Remove Canopy references * Fix script fails if THEANO_FLAGS is not set * Add warning for deprecation of the old backend + minor changes * Default env_th_flags should be an empty string * Remove PYTHONPATH reference from doc, add libgpuarray options first * Add static link to the dev installation instructions * Fix syntax of link
上级 f5207388
显示空白字符变更
内嵌 并排
正在显示 包含 964 行增加 和 1331 行删除
doc/css.inc 0 → 100644
浏览文件 @ c5d3942b
.. _css:
.. raw:: html
<style> .black {color:black} </style>
<style> .blue {color:blue} </style>
<style> .red {color:red} </style>
<style> .green {color:green} </style>
<style> .pink {color:pink} </style>
.. role:: blue
.. role:: red
.. role:: green
.. role:: pink
.. role:: black
doc/dev_start_guide.txt
浏览文件 @ c5d3942b
......@@ -10,7 +10,7 @@ Contributing
You want to contribute to Theano? That is great! This page explain our
workflow and some resource for doing so.
Looking for an idea for a first contribution? Check `github issue
Looking for an idea for a first contribution? Check the `github issues
<https://github.com/Theano/Theano/issues?q=is%3Aopen+is%3Aissue+label%3A%22Easy+fix%22>`_
with a label ``easy fix``. They are good starter. It is recommanded
that you write on the issue you want to work on it. This help make
......@@ -85,8 +85,8 @@ make sure there are no global impacts.
Also, if you are changing GPU code, travis doesn't test that, because
there are no GPUs on the test nodes.
To run the test suite with the default options, you can follow the
instructions of :ref:`testing_installation`.
To run the test suite with the default options, see
:ref:`test_theano`.
Each night we execute all the unit tests automatically, with several
sets of options. The result is sent by email to the `theano-buildbot`_
......@@ -364,7 +364,7 @@ You can choose another name than "central" to reference Theano/Theano
to "central."
You can then test your installation of Theano by following the steps of
:ref:`testing_installation`.
:ref:`test_theano`.
Using your local copy
......
doc/faq.txt
浏览文件 @ c5d3942b
......@@ -10,21 +10,6 @@ Does Theano support Python 3?
------------------------------
We support both Python 2 >= 2.6 and Python 3 >= 3.3.
TypeError: object of type 'TensorVariable' has no len()
-------------------------------------------------------
If you receive the following error, it is because the Python function *__len__* cannot
be implemented on Theano variables:
.. code-block:: python
TypeError: object of type 'TensorVariable' has no len()
Python requires that *__len__* returns an integer, yet it cannot be done as Theano's variables are symbolic. However, `var.shape[0]` can be used as a workaround.
This error message cannot be made more explicit because the relevant aspects of Python's
internals cannot be modified.
Output slight numerical difference
----------------------------------
......@@ -39,7 +24,6 @@ Every Computer Scientist Should Know About Floating-Point Arithmetic
<https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html>`_.
Faster gcc optimization
-----------------------
......@@ -179,33 +163,6 @@ but requires that all nodes in the graph have a C implementation:
f(10.)
Out of memory... but not really
-------------------------------
Occasionally Theano may fail to allocate memory when there appears to be more
than enough reporting:
Error allocating X bytes of device memory (out of memory). Driver report Y
bytes free and Z total.
where X is far less than Y and Z (i.e. X << Y < Z).
This scenario arises when an operation requires allocation of a large contiguous
block of memory but no blocks of sufficient size are available.
GPUs do not have virtual memory and as such all allocations must be assigned to
a continuous memory region. CPUs do not have this limitation because or their
support for virtual memory. Multiple allocations on a GPU can result in memory
fragmentation which can makes it more difficult to find contiguous regions
of memory of sufficient size during subsequent memory allocations.
A known example is related to writing data to shared variables. When updating a
shared variable Theano will allocate new space if the size of the data does not
match the size of the space already assigned to the variable. This can lead to
memory fragmentation which means that a continugous block of memory of
sufficient capacity may not be available even if the free memory overall is
large enough.
Related Projects
----------------
......@@ -226,55 +183,3 @@ Here is a list of some of the known limitations:
interact with the rest of the graph).
- Neither *goto* nor *recursion* is supported or planned within expression graphs.
"float32 / int{32, 64} gives float64"
-------------------------------------
It should be noted that using float32 and int{32, 64} together
inside a function would provide float64 as output.
Since the GPU can't compute this kind of output, it would be
preferable not to use those dtypes together.
To help you find where float64 are created, see the
:attr:`warn_float64` Theano flag.
Theano memory/speed trade-off
-----------------------------
There is a few things you can easily do to change the trade-off
between speed and memory usage. It nothing is said, this affect the
CPU and GPU memory usage.
Could speed up and lower memory usage:
- :ref:`cuDNN <libdoc_cuda_dnn>` default cuDNN convolution use less
memory then Theano version. But some flags allow it to use more
memory. GPU only.
- Shortly avail, multi-GPU.
Could raise memory usage but speed up computation:
- :attr:`config.lib.cnmem` =1 # Do not raise much memory usage, but if you are at the limit of GPU memory available. GPU only.
- :attr:`config.allow_gc` =False
- :attr:`config.optimizer_excluding` =low_memory , GPU only for now.
Could lower the memory usage, but raise computation time:
- :attr:`config.scan.allow_gc` =True # Probably not significant slowdown if config.lib.cnmem is used.
- :attr:`config.scan.allow_output_prealloc` =False
- Use :func:`batch_normalization()
<theano.tensor.nnet.bn.batch_normalization>`. It use less memory
then building a corresponding Theano graph.
- Disable one or scan more optimizations:
- ``optimizer_excluding=scanOp_pushout_seqs_ops``
- ``optimizer_excluding=scan_pushout_dot1``
- ``optimizer_excluding=scanOp_pushout_output``
- Disable all optimization tagged as raising memory usage:
``optimizer_excluding=more_mem`` (currently only the 3 scan optimizations above)
- `float16 <https://github.com/Theano/Theano/issues/2908>`_.
If you want to analyze the memory usage during computation, the
simplest is to let the memory error happen during Theano execution and
use the Theano flags :attr:`exception_verbosity=high`.
doc/index.txt
浏览文件 @ c5d3942b
......@@ -125,6 +125,7 @@ Roughly in order of what you'll want to check out:
* :ref:`install` -- How to install Theano.
* :ref:`introduction` -- What is Theano?
* :ref:`tutorial` -- Learn the basics.
* :ref:`troubleshooting` -- Tips and tricks for common debugging.
* :ref:`libdoc` -- Theano's functionality, module by module.
* :ref:`faq` -- A set of commonly asked questions.
* :ref:`optimizations` -- Guide to Theano's graph optimizations.
......@@ -237,12 +238,15 @@ StackOverflow, follow their guidance for `answering questions <http://stackoverf
NEWS
introduction
requirements
install
updating
tutorial/index
extending/index
dev_start_guide
optimizations
library/index
troubleshooting
glossary
links
internal/index
......
doc/install.txt
浏览文件 @ c5d3942b
.. _install:
Installing Theano
=================
Supported platforms:
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. other architectures are
not well-tested.
Python_ 2 >= 2.6 or Python_ 3 >= 3.3
The development package (``python-dev`` or ``python-devel``
on most Linux distributions) is recommended (see just below).
Python 2.4 was supported up to and including the release 0.6.
Python 3 is supported past the 3.3 release.
``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.
g++ >= 4.2 (for openmp that is currently always used)
more recent version recommended!
`NumPy <http://numpy.scipy.org/>`_ >= 1.7.1
Earlier versions could work, but we don't test it.
`SciPy <http://scipy.org>`_ >= 0.11
Only currently required for sparse matrix and special functions
support, but *highly* recommended. SciPy >=0.8 could work,
but earlier versions have known bugs with sparse matrices.
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://nose.readthedocs.org/en/latest/>`_ >= 1.3.0 and `nose-parameterized <https://pypi.python.org/pypi/nose-parameterized/>`_ >= 0.5.0
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.
`graphiz <http://www.graphviz.org/>`__ and either `pydot-ng <https://github.com/pydot/pydot-ng>`__ or `pydot <https://code.google.com/p/pydot/>`__
To be able to make picture of Theano computation graph.
pydot-ng is a pydot compatible replacement that support newer Python.
`NVIDIA CUDA drivers and SDK`_
Required for GPU code generation/execution on NVIDIA gpus
`libgpuarray`_
Required for GPU/CPU code generation on CUDA and OpenCL devices (see: :ref:`gpuarray`.)
:note: OpenCL support is still minimal for now.
.. _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
.. _libgpuarray: http://deeplearning.net/software/libgpuarray/installation.html
Linux
-----
CentOS 6
~~~~~~~~
:ref:`install_centos6` provides instructions on how to install Theano on CentOS
6, written by the Theano developers. It covers how to install Theano (for
CPU-based computation only) with the distribution-packaged ATLAS, a free fast
implementation of BLAS.
.. Cent OS 6
Ubuntu
~~~~~~
:ref:`install_ubuntu` provides instructions on how to install Theano
on Ubuntu. It covers how to install Theano with the
distribution-packaged OpenBlas or ATLAS. Both are free fast
implementation of BLAS.
Alternative installation on Gentoo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Brian Vandenberg emailed `installation instructions on Gentoo
<http://groups.google.com/d/msg/theano-dev/-8WCMn2FMR0/bJPasoZXaqoJ>`_,
focusing on how to install the appropriate dependencies.
Nicolas Pinto provides `ebuild scripts <https://github.com/npinto/sekyfsr-gentoo-overlay/tree/master/sci-libs/Theano>`_.
Alternative installation on Mandriva 2010.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
.. _linux_basic:
Docker
~~~~~~
Builds of Theano are available as `Docker <https://www.docker.com>`_
images: `Theano Docker (CPU) <https://hub.docker.com/r/kaixhin/theano/>`_ or
`Theano Docker (CUDA) <https://hub.docker.com/r/kaixhin/cuda-theano/>`_. These
are updated on a weekly basis with bleeding-edge builds of Theano.
Examples of running bash in a Docker container are as follows:
.. code-block:: bash
sudo docker run -it kaixhin/theano
sudo nvidia-docker run -it kaixhin/cuda-theano:7.0
For a guide to Docker, see the `official docs <https://docs.docker.com>`_.
CUDA support requires `NVIDIA Docker <https://github.com/NVIDIA/nvidia-docker>`_.
For more details on how to use the Theano Docker images,
consult the `source project <https://github.com/Kaixhin/dockerfiles>`_.
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
This should work under Python 2 or Python 3. To test, run
.. code-block:: bash
nosetests theano
You may need to add ``sudo`` before the ``pip`` command to install into your
system's ``site-packages`` directory. If you do not have administrator access
to your machine, you can install Theano locally (to ~/.local) using
.. code-block:: bash
pip install Theano --user
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_.
``pip`` offers many 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
.. _updating:
Updating Theano
~~~~~~~~~~~~~~~
The following command will update only Theano:
.. code-block:: bash
sudo pip install --upgrade --no-deps theano
The following command will update Theano and Numpy/Scipy (warning bellow):
.. code-block:: bash
sudo pip install --upgrade theano
If you installed NumPy/SciPy with yum/apt-get, updating NumPy/SciPy
with pip/easy_install is not always a good idea. This can make Theano
crash due to problems with BLAS (but see below). The versions of
NumPy/SciPy in the distribution are sometimes linked against faster
versions of BLAS. Installing NumPy/SciPy with
yum/apt-get/pip/easy_install won't install the development package
needed to recompile it with the fast version. This mean that if you
don't install the development packages manually, when you recompile
the updated NumPy/SciPy, it will compile with the slower version. This
results in a slower Theano as well. To fix the crash, you can clear
the Theano cache like this:
.. code-block:: bash
theano-cache clear
.. _install_bleeding_edge:
Bleeding-edge install instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. only:: html
Master Tests Status:
.. raw:: html
<a href="http://travis-ci.org/Theano/Theano/builds"><img src="https://secure.travis-ci.org/Theano/Theano.png?branch=master" /></a>&nbsp;
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 install Theano's dependencies
(like NumPy and SciPy), but not upgrade them. If you wish to upgrade them,
remove the ``--no-deps`` switch to it, but go see a previous warning before doing this.
.. code-block:: bash
pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
or (if you want to install it for the current user only):
.. code-block:: bash
pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git --user
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 (this requires setuptools_ or distribute_ to be installed):
.. 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=~/.local
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.
Specific git commit
~~~~~~~~~~~~~~~~~~~
You can install a specific git commit by using the bleeding edge
instruction and adding @COMMIT_ID to the pip command like:
.. code-block:: bash
pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git@07e9332a0932e90c47ed2a70fc3c7f8a55d2aa23
.. _testing_installation:
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
theano-nose
You should be able to execute it if you followed the instructions above.
If ``theano-nose`` is not found by your shell, you will need to add
``Theano/bin`` to your ``PATH`` environment variable.
.. note::
In Theano versions <= 0.5, ``theano-nose`` was not included. If you
are working with such a version, you can call ``nosetests`` instead
of ``theano-nose``. In that case, some tests will fail by raising
the KnownFailureTest Exception, and will be considered as errors,
but they are nothing to worry about.
.. 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 ``theano-nose`` 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=cuda1``.
See :ref:`libdoc_config` for more information on how to change these
configuration options.
All tests should pass (skipped tests and known failures are normal). 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`.
.. toctree::
:maxdepth: 1
Here are some different way to configure BLAS:
install_ubuntu
install_macos
install_windows
install_centos6
install_others
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``. Note 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, especially 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 g++, but the problem is not fixed yet.
.. note::
If you have problems linking with MKL, `Intel Line Advisor
<http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor>`_
and the `MKL User Guide
<http://software.intel.com/sites/products/documentation/doclib/mkl_sa/11/mkl_userguide_lnx/index.htm>`_
can help you find the correct flags to use.
.. _gpu_linux:
Using the GPU
~~~~~~~~~~~~~
The first thing you'll need for Theano to use your GPU is Nvidia's
GPU-programming toolchain. You should install at least the CUDA driver and the CUDA Toolkit, as
`described here <https://developer.nvidia.com/cuda-toolkit>`_. The CUDA
Toolkit installs a folder on your computer with subfolders *bin*, *lib*,
*include*, and some more too. (Sanity check: The *bin* subfolder should contain an *nvcc*
program which is the compiler for GPU code.) This folder is called the *cuda
root* directory.
You must also add the 'lib' subdirectory (and/or 'lib64' subdirectory if you have a 64-bit Linux
computer) to your ``$LD_LIBRARY_PATH`` environment variable.
You must then tell Theano where the CUDA root folder is, and there are three ways
to do it.
Any one of them is enough.
* Define a $CUDA_ROOT environment variable to equal the cuda root directory, as in ``CUDA_ROOT=/path/to/cuda/root``, or
* add a ``cuda.root`` flag to :envvar:`THEANO_FLAGS`, as in ``THEANO_FLAGS='cuda.root=/path/to/cuda/root'``, or
* add a [cuda] section to your .theanorc file containing the option ``root = /path/to/cuda/root``.
.. note::
On Debian, you can ask the software package manager to install it
for you. We have a user report that this works for Debian Wheezy
(7.0). When you install it this way, you won't always have the
latest version, but we were told that it gets updated
regularly. One big advantage is that it will be updated
automatically. You can try the ``sudo apt-get install
nvidia-cuda-toolkit`` command to install it.
:ref:`Ubuntu instructions <install_ubuntu_gpu>`.
Next, install `libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.
Once that is done, the only thing left is to change the ``device`` option to name the GPU device in your
computer, and set the default floating point computations to float32.
For example: ``THEANO_FLAGS='cuda.root=/path/to/cuda/root,device=cuda,floatX=float32'``.
You can also set these options in the .theanorc file's ``[global]`` section:
.. code-block:: cfg
[global]
device = cuda
floatX = float32
Note that:
* If your computer has multiple GPUs and you use 'device=cuda', the driver
selects the one to use (usually cuda0).
* You can use the program ``nvidia-smi`` to change this policy.
* You can choose one specific GPU by specifying 'device=cudaX', with X the
the corresponding GPU index (0, 1, 2, ...)
* By default, when ``device`` indicates preference for GPU computations,
Theano will fall back to the CPU if there is a problem with the GPU.
You can use the flag 'force_device=True' to instead raise an error when
Theano cannot use the GPU.
Once your setup is complete, head to :ref:`using_gpu` to find how to verify
Once your setup is complete and if you installed the GPU libraries, head to :ref:`testing_the_gpu` to find how to verify
everything is working properly.
.. _Graphviz: http://www.graphviz.org/Download_windows.php
Mac OS
------
There are various ways to install Theano dependencies on a Mac. Here
we describe the process in detail with Canopy, Anaconda, Homebrew or
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.
In academia: Enthought Canopy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are working in academia, the easiest way to install most of the
dependencies is to install
`Canopy <http://enthought.com/products/canopy/>`_.
If you are affiliated with a university (as student or employee), you
can download the installer for free.
The Canopy installation includes in particular Python (and the
development headers), NumPy, SciPy, nose, sphinx, pip, pydot
(but *not* `Graphviz`_, which is necessary for it to work) and the MKL
implementation of blas.
To install the latest Theano release execute this in a terminal:
.. code-block:: bash
$ pip install Theano
If you want the bleeding edge version execute this command instead:
.. code-block:: bash
$ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
See the section `install_bleeding_edge`_ for more
information on the bleeding edge version.
Then you must install the compiler. See :ref:`compiler_osx` below.
.. note::
If you use version 0.6 or later of Theano, we try to automatically
link with the Canopy blas version. Due to Mac OS peculiarities,
this requires user intervention. We detect if the manipulation was
done or not and give an error message explaining what to do in case
it hasn't been done.
Anaconda
~~~~~~~~
An easy way to install most of the dependencies is to install
`Anaconda <http://continuum.io/downloads.html>`_. There is a free
version available to everybody. If you install their ``MKL
Optimizations`` product (free for academic, ~30$ otherwise) Theano
will also be optimized as we will reuse the faster BLAS version
automatically.
The Anaconda installation includes in particular Python (and the
development headers), NumPy, SciPy, nose, sphinx, pip, and a
acceptable BLAS version.
After installing Anaconda, in a terminal execute this command to
install the latest Theano release:
.. code-block:: bash
$ pip install Theano
To install the missing Theano optional dependency (pydot):
.. code-block:: bash
$ conda install pydot-ng
If you want the bleeding edge version instead execute this command:
.. code-block:: bash
$ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
See the section `install_bleeding_edge`_ for more
information on the bleeding edge version.
Then you must install the compiler. See :ref:`compiler_osx` below.
.. note::
If you use version 0.6 or later of Theano, we try to automatically
link with the python library. Due to Mac OS peculiarities, this
requires user intervention. We detect if the user did the
modification and if not, we tell him how to do it.
.. _compiler_osx:
Installing the compiler
~~~~~~~~~~~~~~~~~~~~~~~
Theano officially supports only clang on OS X. This can be installed
by getting XCode from the App Store and running it once to install the
command-line tools.
If you still want to use g++ you can do so by setting its full path in
the theano config flag `gxx`. Note that any bug reports on Mac using
g++ will be ignored unless it can be reproduced with clang.
Homebrew
~~~~~~~~
Install python with homebrew:
.. code-block:: bash
$ brew install python # or python3 if you prefer
This will install pip. Then use pip to install numpy, scipy:
.. code-block:: bash
$ pip install numpy scipy
If you want to use openblas instead of Accelerate, you have to install
numpy and scipy with hombrew:
.. code-block:: bash
$ brew tap homebrew/python
$ brew install numpy --with-openblas
$ brew install scipy --with-openblas
Then install theano as usual:
.. code-block:: bash
$ pip install Theano --user
Or for the bleeding-edge version:
.. code-block:: bash
$ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
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.
If you can't install it from the App Store, look in your MacOS X installation
DVD for an old version. Then update your Mac to update XCode.
- 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()"
.. _gpu_macos:
Using the GPU
~~~~~~~~~~~~~
You should be able to follow the :ref:`Linux <gpu_linux>` instructions to
setup CUDA, but be aware of the following caveats:
* If you want to compile the CUDA SDK code, you may need to temporarily
revert back to Apple's gcc (``sudo port select gcc``) as their Makefiles
are not compatible with MacPort's gcc.
* If CUDA seems unable to find a CUDA-capable GPU, you may need to manually
toggle your GPU on, which can be done with
`gfxCardStatus <http://codykrieger.com/gfxCardStatus>`__.
Next, install `libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.
Once your setup is complete, head to :ref:`using_gpu` to find how to verify
everything is working properly.
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
- 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 inform 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
-------
:ref:`install_windows` provides step-by-step instructions on how to install Theano on 32- or 64-bit Windows systems, using freely available
tools and compilers.
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 officially 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.
Windows Installation References
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. http://stackoverflow.com/questions/9047072/windows-python-version-and-vc-redistributable-version
2. http://stackoverflow.com/questions/1865069/how-to-compile-a-64-bit-application-using-visual-c-2010-express
3. http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/
4. http://stackoverflow.com/questions/126279/c99-stdint-h-header-and-ms-visual-studio
5. http://stackoverflow.com/questions/11182765/how-can-i-build-my-c-extensions-with-mingw-w64-in-python
6. https://mail.python.org/pipermail/python-announce-list/2014-September/010457.html
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
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
To update your current installation see :ref:`updating`.
doc/install_centos6.txt
浏览文件 @ c5d3942b
:orphan:
.. include:: css.inc
.. _install_centos6:
Easy Installation of an optimized Theano on CentOS 6
====================================================
CentOS 6 Installation Instructions
##################################
.. note::
.. warning::
If you want to install the bleeding-edge or development version of Theano
from GitHub, please make sure you are reading `the latest version of this
page <http://deeplearning.net/software/theano_versions/dev/install_centos6.html>`_.
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.
.. include:: requirements.txt
.. note::
.. include:: install_generic.inc
:start-line: 5
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.
Installation steps
~~~~~~~~~~~~~~~~~~
1) ``sudo yum install python-devel python-nose python-setuptools gcc
gcc-gfortran gcc-c++ blas-devel lapack-devel atlas-devel``
2) ``sudo easy_install pip``
3) ``sudo pip install numpy==1.6.1``
4) ``sudo pip install scipy==0.10.1``
5) ``sudo pip install Theano``
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()"``
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 /usr/lib/python2.*/site-packages/theano/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.
Updating Theano
~~~~~~~~~~~~~~~
If you followed these installation instructions, you can execute this command
to update only Theano:
Requirements through System Packages (not recommended)
------------------------------------------------------
.. code-block:: bash
sudo pip install --upgrade --no-deps theano
If you want to also update NumPy/SciPy, 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``.
sudo yum install python-devel python-nose python-setuptools gcc gcc-gfortran gcc-c++ blas-devel lapack-devel atlas-devel
sudo easy_install pip
doc/install_generic.inc 0 → 100644
浏览文件 @ c5d3942b
.. include:: css.inc
.. _install_generic:
Installation
============
Stable Installation
-------------------
Install the latest stable version of Theano with:
.. raw:: html
<div class="highlight"><pre><span class="red">&lt;sudo&gt;</span> pip install <span class="blue">&lt;--user&gt;</span> Theano[test, doc]</pre></div>
- Any argument between <...> is optional.
- Use :red:`sudo` for a root installation.
- Use :blue:`user` for a user installation without admin rights. It will install Theano in your local site-packages.
- [test] will install the requirements for testing.
- [doc] will install the requirements in order to generate the documentation.
If you encountered any trouble, head to the :ref:`troubleshooting` page.
libgpuarray
^^^^^^^^^^^
For the stable version of Theano you need a specific version of libgpuarray,
that has been tagged ``v-9998``.
Download it with:
.. raw:: html
<div class='highlight'><pre>
git clone https://github.com/Theano/libgpuarray.git --tags
git checkout origin/v-9998
cd libgpuarray
</pre></div>
and then follow the `Step-by-step instructions <http://deeplearning.net/software/libgpuarray/installation.html#step-by-step-install>`__.
Bleeding-Edge Installation (recommended)
----------------------------------------
Install the latest, bleeding-edge, development version of Theano with:
.. raw:: html
<div class='highlight'><pre><span class="red">&lt;sudo&gt;</span> pip install <span class="blue">&lt;--user&gt;</span> <span class="pink">&lt;--no-deps&gt;</span> git+https://github.com/Theano/Theano.git#egg=Theano</pre></div>
- Any argument between <...> is optional.
- Use :red:`sudo` for a root installation.
- Use :blue:`user` for a user installation without admin rights. It will install Theano in your local site-packages.
- Use :pink:`no-deps` when you don't want the dependencies of Theano to be installed through pip. This is important when they have already been installed as system packages.
If you encountered any trouble, head to the :ref:`troubleshooting` page.
libgpuarray
^^^^^^^^^^^
Install the latest, development version of libgpuarray following the
`Step-by-step instructions <http://deeplearning.net/software/libgpuarray/installation.html#step-by-step-install>`__.
Developer Installation
----------------------
Install the developer version of Theano with:
.. raw:: html
<div class="highlight"><pre>git clone git://github.com/Theano/Theano.git
cd Theano
<span class="red">&lt;sudo&gt;</span> pip install <span class="blue">&lt;--user&gt;</span> <span class="pink">&lt;--no-deps&gt;</span> <span class="green">-e .</span></pre></div>
- Any argument between <...> is optional.
- Use :red:`sudo` for a root installation.
- Use :blue:`user` for a user installation without admin rights. It will install Theano in your local site-packages.
- Use :pink:`no-deps` when you don't want the dependencies of Theano to be installed through pip. This is important when they have already been installed as system packages.
- :green:`-e` makes your installation *editable*, i.e., it links it to your
source directory.
If you encountered any trouble, head to the :ref:`troubleshooting` page.
libgpuarray
^^^^^^^^^^^
Install the latest, development version of libgpuarray following the
`Step-by-step instructions <http://deeplearning.net/software/libgpuarray/installation.html#step-by-step-install>`__.
doc/install_macos.txt 0 → 100644
浏览文件 @ c5d3942b
.. include:: css.inc
.. _install_macos:
Mac OS Installation Instructions
################################
.. warning::
If you want to install the bleeding-edge or development version of Theano
from GitHub, please make sure you are reading `the latest version of this
page <http://deeplearning.net/software/theano_versions/dev/install_macos.html>`_.
There are various ways to install Theano dependencies on a Mac. Here
we describe the process in detail with Anaconda, Homebrew or 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
alternative instructions here.
.. _theano-users: http://groups.google.com/group/theano-users?pli=1
.. include:: requirements.txt
.. _gpu_macos:
.. attention::
For MacOS you should be able to follow the above instructions to
setup CUDA, but be aware of the following caveats:
* If you want to compile the CUDA SDK code, you may need to temporarily
revert back to Apple's gcc (``sudo port select gcc``) as their Makefiles
are not compatible with MacPort's gcc.
* If CUDA seems unable to find a CUDA-capable GPU, you may need to manually
toggle your GPU on, which can be done with
`gfxCardStatus <http://codykrieger.com/gfxCardStatus>`__.
.. attention::
Theano officially supports only clang on OS X. This can be installed
by getting XCode from the App Store and running it once to install the
command-line tools.
.. include:: install_generic.inc
:start-line: 5
Requirements through Homebrew (not recommended)
-----------------------------------------------
Install python with homebrew:
.. code-block:: bash
$ brew install python # or python3 if you prefer
This will install pip. Then use pip to install numpy, scipy:
.. code-block:: bash
$ pip install numpy scipy
If you want to use openblas instead of Accelerate, you have to install
numpy and scipy with hombrew:
.. code-block:: bash
$ brew tap homebrew/python
$ brew install numpy --with-openblas
$ brew install scipy --with-openblas
Requirements through MacPorts (not recommended)
-----------------------------------------------
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.
If you can't install it from the App Store, look in your MacOS X installation
DVD for an old version. Then update your Mac to update XCode.
- 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
doc/install_others.txt 0 → 100644
浏览文件 @ c5d3942b
.. _install_others:
Other Platform-specific Installations
=====================================
.. warning::
These instructions are not kept up to date.
NVIDIA Jetson TX1 embedded platform
-----------------------------------
.. code-block:: bash
sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ libblas-dev git
pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git --user # Need Theano 0.8 or more recent
Gentoo
------
Brian Vandenberg emailed `installation instructions on Gentoo
<http://groups.google.com/d/msg/theano-dev/-8WCMn2FMR0/bJPasoZXaqoJ>`_,
focusing on how to install the appropriate dependencies.
Nicolas Pinto provides `ebuild scripts <https://github.com/npinto/sekyfsr-gentoo-overlay/tree/master/sci-libs/Theano>`_.
Docker images
-------------
Builds of Theano are available as `Docker <https://www.docker.com/whatisdocker>`_ images:
`Theano Docker (CPU) <https://hub.docker.com/r/kaixhin/theano/>`_ or `Theano Docker (CUDA) <https://hub.docker.com/r/kaixhin/cuda-theano/>`_.
These are updated on a weekly basis with bleeding-edge builds of Theano. Examples of running bash in a Docker container
are as follows:
.. code-block:: bash
sudo docker run -it kaixhin/theano
sudo docker run -it --device /dev/nvidiactl --device /dev/nvidia-uvm --device /dev/nvidia0 kaixhin/cuda-theano:7.0
For a guide to Docker, see the `official docs <https://docs.docker.com/userguide/>`_. For more details on how to use the
Theano Docker images, including requirements for CUDA support, consult the `source project <https://github.com/Kaixhin/dockerfiles>`_.
doc/install_ubuntu.txt
浏览文件 @ c5d3942b
:orphan:
.. include:: css.inc
.. _install_ubuntu:
Easy Installation of an Optimized Theano on Current Ubuntu
==========================================================
For NVIDIA Jetson TX1 embedded platform:
Ubuntu Installation Instructions
################################
.. code-block:: bash
.. warning::
If you want to install the bleeding-edge or development version of Theano
from GitHub, please make sure you are reading `the latest version of this
page <http://deeplearning.net/software/theano_versions/dev/install_ubuntu.html>`_.
.. _gpu_linux:
.. include:: requirements.txt
.. include:: install_generic.inc
:start-line: 5
sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ libblas-dev git
pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git --user # Need Theano 0.8(not yet released) or more recent
Prerequisites through System Packages (not recommended)
-------------------------------------------------------
If you want to acquire the requirements through your system packages and install
them system wide follow these instructions:
For Ubuntu 16.04 with cuda 7.5
......@@ -42,7 +54,6 @@ For Ubuntu 11.10 through 14.04:
.. code-block:: bash
sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ libopenblas-dev git
sudo pip install Theano
On 14.04, this will install Python 2 by default. If you want to use Python 3:
......@@ -56,164 +67,9 @@ For Ubuntu 11.04:
.. code-block:: bash
sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ git libatlas3gf-base libatlas-dev
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.
.. 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.
Bleeding Edge Installs
----------------------
If you would like, instead, to install the bleeding edge Theano (from github)
such that you can edit and contribute to Theano, replace the `pip install Theano`
command with:
.. code-block:: bash
git clone git://github.com/Theano/Theano.git
cd Theano
python setup.py develop --user
cd ..
VirtualEnv
----------
If you would like to install Theano in a VirtualEnv, you will want to pass the
`--system-site-packages` flag when creating the VirtualEnv so that it will pick up
the system-provided `Numpy` and `SciPy`.
.. code-block:: bash
virtualenv --system-site-packages -p python2.7 theano-env
source theano-env/bin/activate
pip install Theano
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.
.. note::
It is possible to have a faster installation of Theano than the one these
instructions 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.
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
Updating Bleeding Edge Installs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Change to the Theano directory and run:
.. code-block:: bash
git pull
Manual Openblas instruction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Manual Openblas installation (deprecated)
-----------------------------------------
The openblas included in some older Ubuntu version is limited to 2
threads. Ubuntu 14.04 do not have this limit. If you want to use more
......@@ -233,90 +89,3 @@ some code that will help you.
# 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
.. _install_ubuntu_gpu:
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>`_.
Ubuntu 14.04:
.. code-block:: bash
sudo apt-get install nvidia-current
sudo apt-get install nvidia-cuda-toolkit # As of October 31th, 2014, provide cuda 5.5, not the latest cuda 6.5
If you want cuda 6.5, you can download packages from `nvidia
<http://developer.nvidia.com/cuda-downloads>`_ for Ubuntu 14.04.
If you downloaded the `run` package (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. On Ubuntu 14.04, you need to run
this in your terminal:
.. code-block:: bash
sudo apt-get update
sudo apt-get install cuda
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/>`_ if the package you downloaded is for another Ubuntu version:
.. 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=cuda 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 available.
Ubuntu 11.04: default gcc version 4.5.2. gcc 4.4.5 available.
Ubuntu 11.10: default gcc version 4.6.1. gcc 4.4.6 and 4.5.3 available.
Ubuntu 12.04 LTS: default gcc version 4.6.3. gcc 4.4.7 and 4.5.3 available.
Ubuntu 12.10: default gcc version 4.7.2. gcc 4.4.7, 4.5.4 and 4.6.3 available.
Ubuntu 13.10: default gcc version 4.8.1. gcc 4.4.7, 4.6.4 and 4.7.3 available.
Ubuntu 14.04: default gcc version 4.8.2, gcc 4.4.7,, 4.6.4, and 4.7.3 available.
doc/install_windows.txt
浏览文件 @ c5d3942b
:orphan:
.. _install_windows:
Windows Installation Instructions
=================================
.. warning::
If you want to install the bleeding-edge or development version of Theano
from GitHub, please make sure you are reading `the latest version of this
page <http://deeplearning.net/software/theano_versions/dev/install_windows.html>`_.
.. warning::
Installation of Theano on Windows
==================================
Theano is mainly developed and tested on Linux Machines.
These instructions show step-by-step how to install Theano and
required dependencies on a 32- or 64-bit system using freely available
......@@ -26,6 +32,8 @@ C/C++ (for Python 2.7 family this has to be Microsoft Visual Studio
version supporting Visual Studio 2008), and GCC (for non-CUDA C code
generated by Theano).
.. _gpu_windows:
Visual Studio and CUDA
######################
......@@ -37,7 +45,6 @@ Studio installation to proceed). Afterwards, the Visual Studio 2010
can be safely removed. If someone knows how to install CUDA 5.5
without a proper Visual Studio installation, please let us know.
First we need to install Microsoft Visual Studio 2010 Express, which
is required to install CUDA. You can download it from
`Visual Studio Express
......@@ -79,7 +86,7 @@ The package will be installed to ``C:\Program Files
(x86)\Common Files\Microsoft\Visual C++ for Python\9.0``.
Finally download the ``stdint.h`` header from
`here <http://msinttypes.googlecode.com/svn/trunk/stdint.h>`_ and save it as
`here <https://sourceforge.net/p/mspgcc/msp430-libc/ci/master/tree/include/stdint.h>`_ and save it as
``C:\Program Files (x86)\Common Files\Microsoft\Visual C++ for
Python\9.0\VC\include\stdint.h``.
......@@ -619,6 +626,3 @@ follows:
dependencies. In the case where it is a dependency, you can use the
`Dependency Walker <http://www.dependencywalker.com/>`__ utility to figure out
which one.
.. _gpu_windows:
doc/requirements.txt 0 → 100644
浏览文件 @ c5d3942b
Requirements
============
.. note::
We only support the installation of the requirements through conda.
.. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
.. _Python: http://www.python.org/
Python_ >= 2.6 or >= 3.3
The development package (python-dev or python-devel on most Linux distributions) is recommended (see just below). Python 2.4 was supported up to and including the release 0.6. Python 3 is supported past the 3.3 release.
`NumPy <http://numpy.scipy.org/>`_ >= 1.7.1 < 1.11.1
Earlier versions could work, but we don’t test it.
`SciPy <http://scipy.org>`_ >= 0.11 < 0.17.1
Only currently required for sparse matrix and special functions support, but highly recommended. SciPy >=0.8 could work, but earlier versions have known bugs with sparse matrices.
`BLAS`_ installation (with Level 3 functionality)
* **Recommended**: MKL, which is free through Conda.
* Alternatively, we suggest to install OpenBLAS, with the development headers (``-dev``, ``-devel``, depending on your Linux distribution).
**Optional requirements**
``python-dev``, ``g++`` >= 4.2
**Highly recommended.** Theano can fall back on a NumPy-based Python execution model, but a C compiler allows for vastly faster execution.
`nose <http://nose.readthedocs.io/en/latest/>`_ >= 1.3.0
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.
`pydot-ng <https://github.com/pydot/pydot-ng>`_
To handle large picture for gif/images.
`NVIDIA CUDA drivers and SDK`_
**Highly recommended** Required for GPU code generation/execution on NVIDIA gpus. See instruction below.
`libgpuarray`_
Required for GPU/CPU code generation on CUDA and OpenCL devices (see: :ref:`gpuarray`.)
Requirements installation through Conda (recommended)
-----------------------------------------------------
Install Miniconda
^^^^^^^^^^^^^^^^^
Follow this `link <http://conda.pydata.org/miniconda.html>`__ to install Miniconda.
.. note::
If you want fast compiled code (recommended), make sure you have g++ (Windows/Linux) or Clang (OS X) installed.
Install requirements and optional packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
conda install numpy scipy mkl <nose> <sphinx> <pydot-ng>
* Arguments between <...> are optional.
Install and configure the GPU drivers (recommended)
---------------------------------------------------
.. warning::
OpenCL support is still minimal for now.
1. Install CUDA drivers
* Follow `this link <https://developer.nvidia.com/cuda-downloads>`__
to install the CUDA driver and the CUDA Toolkit.
* You must reboot the computer after the driver installation.
* Test that it was loaded correctly after the reboot, executing the
command `nvidia-smi` from the command line.
.. note::
Sanity check: The *bin* subfolder should contain an *nvcc*
program. This folder is called the *cuda root* directory.
2. Fix 'lib' path
* Add the 'lib' subdirectory (and/or 'lib64' subdirectory if you have a
64-bit OS) to your ``$LD_LIBRARY_PATH`` environment
variable.
3. Set Theano's config flags
To use the GPU you need to define the *cuda root*. You can do it in one
of the following ways:
* Define a $CUDA_ROOT environment variable to equal the cuda root directory, as in ``CUDA_ROOT=/path/to/cuda/root``, or
* add a ``cuda.root`` flag to :envvar:`THEANO_FLAGS`, as in ``THEANO_FLAGS='cuda.root=/path/to/cuda/root'``, or
* add a [cuda] section to your .theanorc file containing the option ``root = /path/to/cuda/root``.
.. _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
.. _libgpuarray: http://deeplearning.net/software/libgpuarray/installation.html
doc/scripts/docgen.py
浏览文件 @ c5d3942b
......@@ -54,6 +54,10 @@ if __name__ == '__main__':
pythonpath = os.pathsep.join([throot, pythonpath])
sys.path[0:0] = [throot] # We must not use os.environ.
# Make sure we don't use gpu to compile documentation
env_th_flags = os.environ.get('THEANO_FLAGS', '')
os.environ['THEANO_FLAGS'] = 'device=cpu,force_device=True'
def call_sphinx(builder, workdir):
import sphinx
if options['--check']:
......@@ -99,3 +103,6 @@ if __name__ == '__main__':
# To go back to the original current directory.
os.chdir(currentdir)
# Reset THEANO_FLAGS
os.environ['THEANO_FLAGS'] = env_th_flags
doc/troubleshooting.txt 0 → 100644
浏览文件 @ c5d3942b
.. _troubleshooting:
Troubleshooting
###############
Here are Linux troubleshooting instructions. There is a specific `MacOS`_ section.
- :ref:`network_error_proxy`
- :ref:`slow_or_memory`
- :ref:`TensorVariable_TypeError`
- :ref:`out_of_memory`
- :ref:`float64_output`
- :ref:`test_theano`
- :ref:`test_BLAS`
.. _network_error_proxy:
Why do I get a network error when I install Theano
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
.. _TensorVariable_TypeError:
How to solve TypeError: object of type 'TensorVariable' has no len()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you receive the following error, it is because the Python function *__len__* cannot
be implemented on Theano variables:
.. code-block:: python
TypeError: object of type 'TensorVariable' has no len()
Python requires that *__len__* returns an integer, yet it cannot be done as Theano's variables are symbolic. However, `var.shape[0]` can be used as a workaround.
This error message cannot be made more explicit because the relevant aspects of Python's
internals cannot be modified.
.. _out_of_memory:
How to solve Out of memory Error
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Occasionally Theano may fail to allocate memory when there appears to be more
than enough reporting:
Error allocating X bytes of device memory (out of memory). Driver report Y
bytes free and Z total.
where X is far less than Y and Z (i.e. X << Y < Z).
This scenario arises when an operation requires allocation of a large contiguous
block of memory but no blocks of sufficient size are available.
GPUs do not have virtual memory and as such all allocations must be assigned to
a continuous memory region. CPUs do not have this limitation because or their
support for virtual memory. Multiple allocations on a GPU can result in memory
fragmentation which can makes it more difficult to find contiguous regions
of memory of sufficient size during subsequent memory allocations.
A known example is related to writing data to shared variables. When updating a
shared variable Theano will allocate new space if the size of the data does not
match the size of the space already assigned to the variable. This can lead to
memory fragmentation which means that a continugous block of memory of
sufficient capacity may not be available even if the free memory overall is
large enough.
.. _float64_output:
theano.function returns a float64 when the inputs are float32 and int{32, 64}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It should be noted that using float32 and int{32, 64} together
inside a function would provide float64 as output.
Since the GPU can't compute this kind of output, it would be
preferable not to use those dtypes together.
To help you find where float64 are created, see the
:attr:`warn_float64` Theano flag.
.. _test_theano:
How to test that Theano works properly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An easy way to check something that could be wrong is by making sure ``THEANO_FLAGS``
have the desired values as well as the ``~/.theanorc``
Also, check the following outputs :
.. code-block:: bash
ipython
.. code-block:: python
import theano
theano.__file__
theano.__version__
Once you have installed Theano, you should run the test suite.
.. code-block:: bash
python -c "import numpy; numpy.test()"
python -c "import scipy; scipy.test()"
THEANO_FLAGS=''; python -c "import theano; theano.test()"
All Theano tests should pass (skipped tests and known failures are normal). If
some test fails on your machine, you are encouraged to tell us what went
wrong on the ``theano-users@googlegroups.com`` mailing list.
.. warning::
Theano's test should **NOT** be run with ``device=cuda`` or ``device=gpu``
or they will fail. The tests automatically use the gpu, if any, when
needed. If you don't want Theano to ever use the gpu when running tests,
you can set :attr:`config.device` to ``cpu`` and
:attr:`config.force_device` to ``True``.
.. _slow_or_memory:
Why is my code so slow/uses so much memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is a few things you can easily do to change the trade-off
between speed and memory usage. It nothing is said, this affect the
CPU and GPU memory usage.
Could speed up and lower memory usage:
- :ref:`cuDNN <libdoc_cuda_dnn>` default cuDNN convolution use less
memory then Theano version. But some flags allow it to use more
memory. GPU only.
- Shortly avail, multi-GPU.
Could raise memory usage but speed up computation:
- :attr:`config.gpuarray.preallocate` =1 # Preallocates the GPU memory and
then manages it in a smart way. Does not raise much the memory usage, but if
you are at the limit of GPU memory available you might need to specify a
lower value. GPU only.
- :attr:`config.lib.cnmem` =1 # Equivalent on the old backend. GPU only.
- :attr:`config.allow_gc` =False
- :attr:`config.optimizer_excluding` =low_memory , GPU only for now.
Could lower the memory usage, but raise computation time:
- :attr:`config.scan.allow_gc` =True # Probably not significant slowdown if config.lib.cnmem is used.
- :attr:`config.scan.allow_output_prealloc` =False
- Use :func:`batch_normalization()
<theano.tensor.nnet.bn.batch_normalization>`. It use less memory
then building a corresponding Theano graph.
- Disable one or scan more optimizations:
- ``optimizer_excluding=scanOp_pushout_seqs_ops``
- ``optimizer_excluding=scan_pushout_dot1``
- ``optimizer_excluding=scanOp_pushout_output``
- Disable all optimization tagged as raising memory usage:
``optimizer_excluding=more_mem`` (currently only the 3 scan optimizations above)
- `float16 <https://github.com/Theano/Theano/issues/2908>`_.
If you want to analyze the memory usage during computation, the
simplest is to let the memory error happen during Theano execution and
use the Theano flags :attr:`exception_verbosity=high`.
.. _test_BLAS:
How do I configure/test my 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``. Note 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, especially 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 g++, but the problem is not fixed yet.
.. note::
If you have problems linking with MKL, `Intel Line Advisor
<http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor>`_
and the `MKL User Guide
<http://software.intel.com/sites/products/documentation/doclib/mkl_sa/11/mkl_userguide_lnx/index.htm>`_
can help you find the correct flags to use.
.. 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.
Testing 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.
.. _MacOS:
Mac OS
------
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.
.. _theano-users: http://groups.google.com/group/theano-users?pli=1
Please inform 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`_).
doc/tutorial/using_gpu.txt
浏览文件 @ c5d3942b
.. _using_gpu:
=============
......@@ -19,11 +18,33 @@ There are two ways currently to use a gpu, one that should support any OpenCL
device as well as NVIDIA cards (:ref:`gpuarray`), and the old backend that
only supports NVIDIA cards (:ref:`cuda`).
Using the GPU in Theano is as simple as setting the ``device`` configuration
flag to ``device=cuda`` (or ``device=gpu`` for the old backend). You can optionally target a specific gpu by specifying
the number of the gpu as in e.g. ``device=cuda2``. You also need to set the
default floating point precision.
For example: ``THEANO_FLAGS='cuda.root=/path/to/cuda/root,device=cuda,floatX=float32'``.
You can also set these options in the .theanorc file's ``[global]`` section:
.. code-block:: cfg
[global]
device = cuda
floatX = float32
.. warning::
If you want to use the new GpuArray backend, make sure to have the
development version of Theano installed. The 0.8.X releases have not
been optimized to work correctly with the new backend.
The old CUDA backend will be deprecated soon, in favor of the new libgpuarray
backend.
.. note::
* If your computer has multiple GPUs and you use ``device=cuda``, the driver
selects the one to use (usually gpu0).
* You can use the program ``nvidia-smi`` to change this policy.
* By default, when ``device`` indicates preference for GPU computations,
Theano will fall back to the CPU if there is a problem with the GPU.
You can use the flag ``force_device=True`` to instead raise an error when
Theano cannot use the GPU.
.. _gpuarray:
......@@ -31,19 +52,32 @@ GpuArray Backend
----------------
If you have not done so already, you will need to install libgpuarray
as well as at least one computing toolkit. Instructions for doing so
are provided at `libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.
as well as at least one computing toolkit (CUDA or OpenCL). Detailed
instructions to accomplish that are provided at
`libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.
To install Nvidia's GPU-programming toolchain (CUDA) and configure
Theano to use it, see the installation instructions for
:ref:`Linux <gpu_linux>`, :ref:`MacOS <gpu_macos>` and :ref:`Windows <gpu_windows>`.
While all types of devices are supported if using OpenCL, for the
remainder of this section, whatever compute device you are using will
be referred to as GPU.
.. warning::
If you want to use the new GpuArray backend, make sure to have the
development version of Theano installed. The 0.8.X releases have not
been optimized to work correctly with the new backend.
.. warning::
The backend was designed to support OpenCL, however current support is
incomplete. A lot of very useful ops still do not support it because they
were ported from the old backend with minimal change.
.. _testing_the_gpu:
Testing Theano with GPU
~~~~~~~~~~~~~~~~~~~~~~~
......
doc/updating.txt 0 → 100755
浏览文件 @ c5d3942b
.. include:: css.inc
.. _updating:
Updating Theano
===============
Follow one of these three sections depending on how you installed Theano.
You should update frequently, bugs are fixed on a very regular basis, and features are
added even more frequently!
Stable Installation
-------------------
The following command will update only Theano:
.. raw:: html
<pre><span class="red">&#60;sudo&#62;</span> pip install <span class="blue">&#60;--user&#62;</span> <span class="pink">&#60;--no-deps&#62;</span> theano</pre>
- Use :red:`sudo` for a root installation.
- Use :blue:`user` for a user installation without admin rights. It will install Theano in your local site-packages.
- Use :pink:`no-deps` when you don't want the dependencies of Theano to not be installed through pip. This is important when they have already been installed as system packages.
.. warning::
If you installed NumPy/SciPy with yum/apt-get, updating NumPy/SciPy
with pip/easy_install is not always a good idea. This can make Theano
crash due to problems with BLAS. The versions of
NumPy/SciPy in the distribution are sometimes linked against faster
versions of BLAS. Installing NumPy/SciPy with
yum/apt-get/pip/easy_install won't install the development package
needed to recompile it with the fast version.
To fix a possible crash, you can clear
the Theano cache like this:
.. code-block:: bash
theano-cache clear
Bleeding-Edge Installation
--------------------------
The following command will update your bleeding-edge version of Theano
.. raw:: html
<div style="width:100%"><pre><span class="red">&#60;sudo&#62;</span> pip install <span class="blue">&#60;--user&#62;</span> <span class="pink">&#60;--no-deps&#62;</span> git+https://github.com/Theano/Theano.git#egg=Theano</pre></div>
- Use :red:`sudo` for a root installation.
- Use :blue:`user` for a user installation without admin rights. It will install Theano in your local site-packages.
- Use :pink:`no-deps` when you don't want the dependencies of Theano to not be installed through pip. This is important when they have already been installed as system packages.
.. warning::
If you installed NumPy/SciPy with yum/apt-get, updating NumPy/SciPy
with pip/easy_install is not always a good idea. This can make Theano
crash due to problems with BLAS. The versions of
NumPy/SciPy in the distribution are sometimes linked against faster
versions of BLAS. Installing NumPy/SciPy with
yum/apt-get/pip/easy_install won't install the development package
needed to recompile it with the fast version.
To fix a possible crash, you can clear
the Theano cache like this:
.. code-block:: bash
theano-cache clear
Developer Installation
----------------------
To update your library to the latest revision, change directory (``cd``)
to your ``Theano`` folder and execute the following command:
.. warning::
The following assumes you have knowledge of git and know how to do a rebase.
.. code-block:: bash
git pull --rebase
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论