Installation¶
Let’s get you started using neon to build deep learning models!
Requirements¶
Neon runs on Python 2.7 or Python 3.4+ and we support Linux and Mac OS X machines. Before install, please ensure you have recent versions of the following packages (different system names shown):
Ubuntu | OSX | Description |
---|---|---|
python-pip | pip | Tool to install python dependencies |
python-virtualenv (*) | virtualenv (*) | Allows creation of isolated environments ((*): This is required only for Python 2.7 installs. With Python3: test for presence of venv with python3 -m venv -h ) |
libhdf5-dev | h5py | Enables loading of hdf5 formats |
libyaml-dev | pyaml | Parses YAML format inputs |
pkg-config | pkg-config | Retrieves information about installed libraries |
Note
To enable Aeon, neon’s dataloader, several optional libraries should be installed. For image processing, install OpenCV. For audio and video data, install ffmpeg. We recommend installing with a package manager (e.g. apt-get or homebrew). If you have encountered error messages about failing to install aeon while building neon, please visit aeon page for how to install prerequisites for aeon to enable neon with aeon data loader.
Additionally, there are several other libraries.
- Neon v2.0.0+ by default comes with Intel Math Kernel Library (MKL) support, which enables multi-threading operations on Intel CPU. It is the recommended library to use for best performance on CPU. When installing neon, MKL support will be automatically enabled.
- (optional) If interested to compare multi-threading performance of MKL optimized neon, install OpenBLAS, then recompile numpy with links to openBLAS (see sample instructions here). While neon will run on the CPU with OpenBLAS, you’ll get better performance using MKL on CPUs or CUDA on GPUs.
- Enabling neon to use GPUs requires installation of CUDA SDK and drivers. We support Pascal , Maxwell and Kepler GPU architectures, but our backend is optimized for Maxwell GPUs. Remember to add the CUDA path to your environment variables.
For GPU users, remember to add the CUDA path. For example, on Ubuntu:
export PATH="/usr/local/cuda/bin:"$PATH
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:/usr/local/cuda/lib:/usr/local/lib:"$LD_LIBRARY_PATH
Or on Mac OS X:
export PATH="/usr/local/cuda/bin:"$PATH
export DYLD_LIBRARY_PATH="/usr/local/cuda/lib:"$DYLD_LIBRARY_PATH
Installation¶
We recommend installing neon within a virtual environment to ensure a self-contained environment. To install neon within an already existing virtual environment, see the System-wide Install section. If you use the Anaconda python distribution, please see the Anaconda Install section. Otherwise, to setup neon in this manner, run the following commands:
git clone https://github.com/NervanaSystems/neon.git
cd neon; git checkout latest; make
The above checks out the latest stable release (e.g. a tagged release version v2.6.0) and build neon. Alternatively, you can check out and build the latest master branch:
git clone https://github.com/NervanaSystems/neon.git
cd neon; make
This will install the files in the neon/.venv/
directory and will use the python version in the
default PATH. Note that neon would automatically download the released MKLML library that
features MKL support.
To instead force a Python2 or Python3 install, supply this as an optional parameter:
make python2
Or:
make python3
To activate the virtual environment, type
. .venv/bin/activate
You will see the prompt change to reflect the activated environment. To start neon and run the MNIST multi-layer perceptron example (the “Hello World” of deep learning), enter
examples/mnist_mlp.py
Note that since neon v2.1 the above is equivalent to explicitly add -b mkl
for better performance on Intel CPUs. In other words, mkl backend is the default backend
examples/mnist_mlp.py -b mkl
Note
To achieve best performance, we recommend setting KMP_AFFINITY and OMP_NUM_THREADS in this way: export KMP_AFFINITY=compact,1,0,granularity=fine
and export OMP_NUM_THREADS=<Number of Physical Cores>
. You can set these environment variables in bash and do source ~/.bashrc
to activate it. You may need to activate the virtual environment again after sourcing bashrc. For detailed information about KMP_AFFINITY, please read here: https://software.intel.com/en-us/node/522691. We encourage users to experiment with this thread affinity configurations to achieve even better performance.
When you are finished, remember to deactivate the environment
deactivate
Congratulations, you have installed neon! Next, we recommend you learn how to run models in neon and walk through the MNIST multilayer perceptron tutorial.
Virtual Environment¶
Virtualenv
is a python tool that keeps the dependencies and packages
required for different projects in separate environments. By default,
our install creates a copy of python executable files in the
neon/.venv
directory. To learn more about virtual environments, see
the guide at http://docs.python-guide.org/en/latest/dev/virtualenvs/.
System-wide install¶
If you would prefer not to use a new virtual environment, neon can be installed system-wide with
git clone https://github.com/NervanaSystems/neon.git
cd neon && make sysinstall
To install neon in a previously existing virtual environment, first activate
that environment, then run make sysinstall
. Neon will install the
dependencies in your virtual environment’s python folder.
Pip install¶
Neon v2.4.0 and after is pip installable via pypi with package name nervananeon.
pip install nervananeon
It is noted aeon needs to be installed separately. The latest release v2.6.0 uses aeon v1.3.0.
Anaconda install¶
If you have already installed and configured the Anaconda distribution of python, follow the subsequent steps.
First, configure and activate a new conda environment for neon:
conda create --name neon pip
source activate neon
Now clone and run a system-wide install. Since the install takes place inside a conda environment, the dependencies will be installed in your environment folder.
git clone https://github.com/NervanaSystems/neon.git
cd neon && make sysinstall
When complete, deactivate the environment:
source deactivate
Docker¶
If you would prefer having a containerized installation of neon and its dependencies, the open source community has contributed the following Docker images:
Support¶
For any bugs or feature requests please:
- Search the open and closed issues list to see if we’re already working on what you have uncovered.
- Check that your issue/request isn’t answered in our Frequently Asked Questions (FAQ) or neon-users Google group.
- File a new issue or submit a new pull request if you have some code to contribute. See our contributing guide.
- For other questions and discussions please post a message to the neon-users Google group.