Installation

ELEKTRONN2

There are two supported ways to install ELEKTRONN2: With the package managers conda or pip. We highly recommend using the conda install method.

Note

ELEKTRONN2 is supported on Linux (x86_64), with Python versions 2.7, 3.4, 3.5 and 3.6. Everything else is untested, but some other platforms might work as well.

Installing with conda

The recommended way to install ELEKTRONN2 is to use the conda package manager, which is included in Anaconda (Miniconda also works). The ELEKTRONN2 package is hosted by the conda-forge channel, so you first need to add it to your local channel list if you haven’t yet done this:

conda config --add channels conda-forge

Then you can either install ELEKTRONN2 directly into your current environment:

conda install elektronn2

… or create a new conda env just for ELEKTRONN2:

conda create -n elektronn2_env elektronn2

Optionally run conda activate elektronn2_env to activate the new environment and ensure all ELEKTRONN2 executables are on your PATH. The effects of the activation only last for the current shell session, so remember to repeat this step after re-opening your shell.

Installing with pip

You can install the current version of ELEKTRONN2 and all of its dependencies with the pip package manager. For Python 3, run:

python3 -m pip install elektronn2

Or if you want to install ELEKTRONN2 for Python 2:

python2 -m pip install elektronn2

To prevent permission errors and conflicts with other packages, we suggest that you run these pip install commands inside a virtualenv or a conda env.

Please do not attempt to use sudo or the root account for pip install, because this can overwrite system packages and thus potentially destroy your operating system (this is not specific to ELEKTRONN2, but a general flaw in pip and applies to all packages (see this issue). pip install --user can be used instead, but this method can also break other Python packages due to the version/precedence conflicts between system and user packages.

CUDA and cuDNN

In order to use Nvidia GPUs for accelleration, you will need to additionally install CUDA. Install Nvidia’s CUDA toolkit by following the instructions on the Nvidia website or install it with your system package manager.

Even higher performance for training and inference in deep convolutional neural networks can be enabled by installing the cuDNN library. Once it is installed, ELEKTRONN2 will automatically make use of it.

For example if you use Arch Linux, both libraries can be installed with:

sudo pacman -S cuda cudnn

If you don’t have root rights on your machine, you can install CUDA and cuDNN to a custom path in your $HOME directory. If you do that, don’t forget to update your environment variables, e.g. by adding these lines to you ~/.bashrc-file (assuming you have installed both to ~/opt/cuda/):

export PATH=~/opt/cuda/bin:$PATH
export LD_LIBRARY_PATH=~/opt/cuda/lib64:$LD_LIBRARY_PATH

Theano configuration

Lastly, the Theano back end needs to be configured. It is responsible for optimizing and compiling ELEKTRONN2’s computation graphs. Create the file ~/.theanorc and put the following lines into it:

[global]
floatX = float32
linker = cvm_nogc

[nvcc]
fastmath = True

Note

The cvm_nogc linker option disables garbage collection. This increases GPU-RAM usage but gives a significant performance boost. If you run out of GPU-RAM, remove this option (or set it to cvm).

If your CUDA installation is in a custom location (e.g. ~/opt/cuda/) and is not found automatically, additionally set the cuda.root option in your ~/.theanorc:

[cuda]
root = ~/opt/cuda

If you always want to use the same GPU (e.g. GPU number 0) for ELEKTRONN2 and don’t want to specify it all the time in your command line, you can also configure it in ~/.theanorc:

[global]
device = gpu0

More options to configure Theano can be found in the theano.config documentation.