# 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):

``` shell
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](https://am3.readthedocs.io/en/latest/running_with_docker.html) and the documentation in our [Dockerfile]([pyenv](https://gitlab.desy.de/am3/am3/-/blob/master/Dockerfile))). 

- Run AM³ directly in C++ (see [this page](https://am3.readthedocs.io/en/latest/running_from_cpp.html)).

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](https://github.com/conda-forge/miniforge?tab=readme-ov-file#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:
```shell
$ 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](https://gitlab.desy.de/am3/am3), 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):
```shell
$ 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](https://github.com/pyenv/pyenv) to manage Python versions.

On macOS, use [homebrew](https://brew.sh/) 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)
```