Installation

When you simply want to use the AM³ code for your application, we recommend to install it via conda/mamba/micromamba from conda-forge, e.g. (for macOS and Linux):

conda install am3 -c conda-forge

For development, it might be more convenient to have a local pip installation. Alternatively, you can also

Install and run AM³ with Docker (see this page and the documentation in our Dockerfile).
Run AM³ directly in C++ (see this page).

Due to library dependencies we stronlgy recommend compiling and using AM³ in the same environment! This implies (a) compiling on the machine (or laptop) that you want to use it on, ideally (b) also in the same Python environment. The latter can be realised by creating a fixed conda environment in which you first compile and later also run the code.

Installation using conda (macOS and Linux)

We recommend using the miniforge3 conda distribution. It is open source and comes with the fast mamba tool.

Download and install the version for your operating system and architecture. If you have a mac with apple silicon chip (M1 / M2 / M3 etc.) make sure to choose OS X / arm64 (Apple Silicon).

Create a new environment for am3, installing the necessary dependencies:

$ mamba create -n am3env python=3.12 am3 astropy gammapy matplotlib seaborn requests

The other libraries (astropy gammapy matplotlib seaborn requests) are only used in our example notebooks.

Don’t forget to activate the environment (you will need to do this everytime you want to use AM³):

$ mamba activate am3env

Local installation for development using pip inside conda

Download the latest release, or clone the repository with git clone https://gitlab.desy.de/am3/am3.git

Here we describe how to compile AM³ yourself into a Python3 module. As for the above section, set up a conda/mamba environment (note that you need the other packages as above only for the example notebooks):

$ mamba create -n am3env python=3.12 compilers gsl eigen numpy

You can install AM³ now, either by directly pointing it to the git repository

(am3env) $ pip install git+https://gitlab.desy.de/am3/am3

or if you cloned the repository, in the base directory of the repository

(am3env) $ pip install .

After changes to the C++ code, you can just recompile the am3 library by reinstalling.

Installation using system packages

Alternatively you can also install AM³ into your existing setup, which we describe below.

Dependencies on Linux

External dependencies for both Python and C++ builds:

Eigen3 library: install through your standard package manager (apt/dnf/…) e.g. using apt: sudo apt install libeigen3-dev
gsl library: install through your standard package manager (apt/dnf/…) e.g. using apt: sudo apt install libgsl-dev libgsl
C++ compiler: install through your standard package manager (apt/dnf/…) e.g. using apt: sudo apt install g++

For the Python build: python 3.7+

For the C++ build:

cmake: install through your standard package manager (apt/dnf/…) e.g. using apt: sudo apt install cmake

Dependencies on macOS

Tip: when not using conda (see above), you might want to use pyenv to manage Python versions.

On macOS, use homebrew to install the dependencies:

$ brew install libomp gsl eigen cmake

You need to export this environment variable so that cmake can find OpenMP:

export CMAKE_PREFIX_PATH="/opt/homebrew/opt/libomp"

Installing the python bindings

Just run pip install ..

You may want to create a new virtual environment for am3 first, e.g.:

$ python -m venv venv
$ source venv/bin/activate
$ pip intall venv

You can also install am3 in “development mode”, this will rebuild the C++ code on import automatically, so you can even change the C++ code and immediately see the effect of changes:

$ python3 -m venv venv
$ source venv/bin/activate
$ pip install 'scikit-build-core[pyproject]' pybind11 ninja cmake'
$ pip install -e '.[all]' --no-build-isolation --config-settings=editable.rebuild=true --config-settings=build-dir=build

Installing AM3 as a C++ library

The C++ library is using cmake as a build system, to configure, build and install AM³:

$ cmake -S . -B build
$ cmake --build build
$ cmake --install build

Common cmake configuration options

All these options need to be passed to the first cmake call above (cmake -S . -B build).

To install am3 into a custom location, as you might not have access to /usr/bin, add
```
-DCMAKE_INSTALL_PREFIX=~/.local/am3
```
If you just want to build the C++ library, and not the python bindings:
```
-DPYTHON=OFF
```

Using the AM3 C++ library

See docs/examples/cplusplus/CMakeLists.txt for a minimal example. It boils down to:

find_package(AM3 CONFIG REQUIRED)
target_link_libraries(your_program PRIVATE AM3::am3)