Installation.qmd

# Installation

ANNarchy is designed to run on GNU/Linux and OSX. It relies mostly on a C++ compiler (g++ or clang++), Cython (C for Python extension) and Python (Numpy, Sympy) libraries. 

Installation on Windows is only possible using the WSL (Windows Subsystem for Linux) or a VM.

## Download

The source code of ANNarchy can be downloaded on github:

```bash
git clone https://github.com/ANNarchy/ANNarchy.git
```

## Installation on GNU/Linux

### Dependencies

ANNarchy depends on a number of packages that should be easily accessible on recent GNU/Linux distributions. The classical way to install these dependencies is through your package manager, or using full Python distributions such as Anaconda. Older versions of these packages may work but have not been tested.

* `python` >= 3.10 (with the development files, e.g. `python-dev` or `python-devel`)
* `g++` >= 7.4 or `clang++` >= 3.4
* `cmake` >= 3.16
* `setuptools` >= 65.0
* `nanobind` >= 2.4.0
* `cython` >= 3.0
* `numpy` >= 1.21
* `sympy` >= 1.11
* `scipy` >= 1.9
* `matplotlib` >= 3.0
* `tqdm` >= 4.60

Additionally, the following packages are optional but strongly recommended:

* `lxml` (to save the networks in `.xml` format).
* `h5py` (to export data in `.h5` format).
* `pandoc` (for `report()`).
* `tensorflow` (for the `ann_to_snn_conversion` extension)
* `tensorboardX` (for the `logging` extension).

The CUDA-SDK is available on the official [website](https://developer.nvidia.com/cuda-downloads) (we recommend to use at least a SDK version \> 6.x). For further details on installation etc., please consider the corresponding Quickstart guides ([Quickstart_8.0](https://developer.nvidia.com/compute/cuda/8.0/prod/docs/sidebar/CUDA_Quick_Start_Guide-pdf) for the SDK 8.x).

ANNarchy works with full Python distributions such as Anaconda, as well as in virtual environments and Jupyter notebooks.

:::callout-note

On a fresh install of Ubuntu 22.04, here are the minimal system packages to install before ANNarchy:

```bash
sudo apt install build-essential git python3-dev python3-setuptools python3-pip 
```

:::


### Installation

#### Using pip

Stable releases of ANNarchy are available on PyPi:

```bash
pip install ANNarchy
```

or:

```bash
pip install ANNarchy --user
```

if you do not have administrator permissions. Omit `--user` in a virtual environment.

You may also install directly the latest commit in the `master` (stable) or `develop` branches with:

```bash
pip install git+https://github.com/ANNarchy/ANNarchy.git@master
```

#### Using the source code

Installation of ANNarchy from source is possible using `pip` in the top-level directory:

```bash
pip install .
```

or in development mode:

```bash
pip install -e .
```

Using `python setup.py install` is deprecated, but still works.

#### C++ compiler

By default, ANNarchy will use the GNU C++ compiler `g++`, which should be in your PATH. If you want to use another compiler (clang++, icc), you can edit the configuration file located at `$HOME/.config/ANNarchy/annarchy.json` (created during installation) accordingly. By default, it is:

``` {.json}
{
    "openmp": {
        "compiler": "g++",
        "flags": "-march=native -O3"
    },
    "cuda": {
        "compiler": "nvcc",
        "flags": "",
        "device": 0,
        "path": "/usr/local/cuda"
    }
}
```

The (path to the) compiler can be changed in the `openmp` section (ignore the `cuda` section if you do not have a GPU).

You can also change the compiler flags if you know what you are doing. `-O3` does not always lead to faster simulation times, nor to exact simulations. 


#### CUDA

If ANNarchy detects the CUDA SDK during installation, it will prepare the required modules. You need to make sure that the CUDA compiler `nvcc` is accessible in your path.

The main problem with CUDA is that the binaries, headers and libraries are installed at different locations depending on the version: `/usr/local/cuda`, `/usr/local/cuda-7.0` or `/usr/local/cuda-8.0`. There is unfortunately no way for ANNarchy to guess the installation path.

A first thing to help ANNarchy find the CUDA libraries is to define the `LD_LIBRARY_PATH` environment variable and have point at the `lib64/` subfolder:

```bash
export LD_LIBRARY_PATH=/usr/local/cuda-8.0/lib64/:$LD_LIBRARY_PATH
```

This should in most cases work if you have only one CUDA installation. Otherwise, it is needed that you indicate where the CUDA libraries are, by modifying the ANNarchy configuration file located at `$HOME/.config/ANNarchy/annarchy.json`:

``` {.json}
{
    "openmp": {
        "compiler": "g++",
        "flags": "-march=native -O3"
    },
    "cuda": {
        "compiler": "nvcc",
        "flags": "",
        "device": 0,
        "path": "/usr/local/cuda"
    }
}
```

Simply point the `['cuda']['path']` field to the right location (without `lib64/`). If the nvcc compiler binary is at a different location, the absolute path to the nvcc can be provided by `['cuda']['compiler']` field.

It can happen that the detection of CUDA fails during installation, as some environment variables are not set. In this case try:

```bash
env "PATH=$PATH" "LIBRARY_PATH=$LIBRARY_PATH" pip install .
```

## Installation on MacOS X

Installation on MacOS X is in principle similar to GNU/Linux:

```bash
pip install ANNarchy
```

We strongly advise using a full Python distribution like [Miniforge](https://github.com/conda-forge/miniforge), or a package manager like [Homebrew](https://brew.sh/) rather than the default python provided by Apple.

The main issue is the choice of the C++ compiler:

### Using LLVM/clang

If not done already, you should first install the [Xcode Command Line Tools](https://developer.apple.com/) and [Homebrew](https://brew.sh/) (see <https://mac.install.guide/commandlinetools/> for a guide) to get the LLVM clang++ compiler.

The major drawback of Apple's clang++ is that it still does not support OpenMP for parallel computing. Any attempt to use OpenMP with ANNarchy using this compiler will crash.

It is strongly advised to use a more recent version of `clang++` such as the one offered by homebrew:

```bash
brew install llvm
```

and update your shell config to use this version of `clang++` instead of Apple's (adapt the paths accordingly): 

```bash
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
export LDFLAGS="-L/opt/homebrew/opt/llvm/lib:$LDFLAGS"
export CPPFLAGS="-I/opt/homebrew/opt/llvm/include:$CPPFLAGS"
```

If you have a MX arm64 processor, it might be beneficial to tell clang++ to use optimizations for that hardware. Open the configuration file at `$HOME/.config/ANNarchy/annarchy.json` and add the following compiler flag (adapt it to your processor):

``` {.json}
{
    "openmp": {
        "compiler": "clang++",
        "flags": "-mcpu=apple-m1 -O3"
    },
    "cuda": {
        "compiler": "nvcc",
        "flags": "",
        "device": 0,
        "path": "/usr/local/cuda"
    }
}
```

### Using gcc

In order to benefit from OpenMP parallelization, you can also install `gcc`, the GNU C compiler, using [Homebrew](https://brew.sh/):

```bash
brew install gcc
```

You will get the command-line C++ compiler with a **version number**, e.g.:

```bash
g++-11
```

The `g++` executable is a symlink to Apple's clang++, do not use it...

You now have to tell ANNarchy which compiler to use, even if it is in your PATH. After installing ANNarchy, a config file is created in `$HOME/.config/ANNarchy/annarchy.json`. Open it and change the `openmp` entry to:

``` {.json}
{
    "openmp": {
        "compiler": "g++-11",
        "flags": "-march=native -O3"
    },
    "cuda": {
        "compiler": "nvcc",
        "flags": "",
        "device": 0,
        "path": "/usr/local/cuda"
    }
}
```


:::callout-warning

The CUDA backend is not available on OS X.
:::