GammaLearn

GammaLearn is a collaborative project to apply deep learning to the analysis of low-level Imaging Atmospheric Cherenkov Telescopes such as CTA. It provides a framework to easily train and apply models from a configuration file.

Table of Contents

1. Installation
2. Usage
3. Contributing
4. Cite Us
5. License

Installation

For users

GammaLearn uses uv to manage environments and dependencies.

Quick start (local installation)

Prerequisites

Install uv if needed:

curl -Ls https://astral.sh/uv/install.sh | sh

Then install GammaLearn, selecting the cpu or gpu extra depending on your hardware (this pulls in the matching torch/torchvision build):

uv init && uv add gammalearn --extra cpu

or

uv init && uv add gammalearn --extra gpu

For Developers

GammaLearn uses uv to manage environments and dependencies.

Dependencies are defined in pyproject.toml using optional dependency groups:

• cpu → CPU-only installation (used in CI)
• gpu → GPU-enabled installation
• test → testing dependencies

Torch and torchvision are installed via optional extra dependencies.

Clone the repository:

git clone https://gitlab.in2p3.fr/gammalearn/gammalearn.git
cd gammalearn

Install dependencies using uv:

uv sync --extra cpu

For GPU environments:

uv sync --extra gpu

Run GammaLearn:

uv run gammalearn --help

Run tests:

uv run --locked --extra cpu --group test pytest

Note: If dependencies are modified, update the lock file before committing:

uv lock

Development with Docker (alternative to local uv setup)

To pull the container of the branch you use to develop:

docker pull gitlab-registry.in2p3.fr/gammalearn/gammalearn/prod:your_branch_name

Clone gammalearn locally and go in the gammalearn directory:

git clone https://gitlab.in2p3.fr/gammalearn/gammalearn.git && cd gammalearn

Enter the container while mounting the source code, and install gammalearn

# - get a shell with interactive mode
# - mount gammalearn sources in "bind" mode with --mount
# - use your host user uid and gid (-u $(id -u):$(id -g)) to have write permissions in the mounted gammalearn sources
# - set working directory to /src
# - optionally: set pull policy to always to always get the latest image for your branch
docker run --rm -it --mount type=bind,source=.,destination=/src -w /src --pull=always -u $(id -u):$(id -g) gitlab-registry.in2p3.fr/gammalearn/gammalearn/prod:your_branch_name

# Develop !

Usage with an IDE (vscode example)

Many IDE's offer the possibility to start or interact with running docker containers. In VScode, this is handled by the "dev container" extension included in the remote development extension pack (see the extension documentation). The extension can start a container and automatically install a vs-code server inside the container, allowing to transparently develop the software while using the environment from inside the container. The following devcontainer.json configuration allows to start a development container with the right permissions and build gammalearn from the mounted sources. As examples, the python extension and ruff linter are installed in the vs-code server running in the container.

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/miniconda
{
	"image": "gitlab-registry.in2p3.fr/gammalearn/gammalearn/prod:your_branch_name",
	"workspaceMount": "source=${localWorkspaceFolder},target=/src,type=bind",
	"workspaceFolder": "/src",
	"postCreateCommand": "uv sync --all-extras",
	"postAttachCommand": "uv run gammalearn --help",
	"runArgs": [ "--network=host"],
	"customizations": {
		// Configure properties specific to VS Code.
		"vscode": {
			// Add the IDs of extensions you want installed when the container is created.
			"extensions": [
				"charliermarsh.ruff",
				"ms-python.python",
				"ms-python.vscode-pylance",
				"njpwerner.autodocstring",
				"tamasfe.even-better-toml",
				"wmaurer.change-case"
			]
		}
	}
}

Note: By default, the dev containers extension will not re-pull the specified image unless you rebuild the container in vscode. Make sure to pull the latest container for your branch before entering the container.

Once the container is running, you can enter it from another external terminal with

# Get the container ID of your dev container started with vscode
docker ps
# Get a shell in the container
docker exec -it -w /src container_ID bash​

Usage

Run an experiment (Production)

We recommend the use of apptainer. To get the production image of the version of gammalearn you want to use, for instance to get gammalearn v0.13.0, use apptainer pull:

apptainer pull docker://gitlab-registry.in2p3.fr/gammalearn/gammalearn:v0.13.0

This will create a .sif container file that contains a ready to use gammalearn installation. Warning: apptainer can use several GB of disk space as cache when building the .sif file. By default, the cache is located in your home folder ~/.apptainer/cache. You can change this location by setting the APPTAINER_CACHEDIR environment variable. Clean apptainer's cache with apptainer cache clean

You can now run gammalearn from the container to test it:

apptainer run path_to_your_sif_file.sif gammalearn --help

You can run an experiment using apptainer run. Since apptainer containers are read-only by default, you will need to mount the paths to your input and output files. To use nvidia gpus, you will need to specify the --nv option as well. A typical command example:

# Run the experiment in the container
# Parameters:
# --nv                  to use nvidia gpus from inside the container
# CUDA_VISIBLE_DEVICES  env variable used by pytorch to discover the gpus
# NUMBA_CACHE_DIR       a writable directory where numba can store its compiled functions
#                       (needs to be outside of the container, which is read-only)
# CTAPIPE_CACHE         ctapipe needs a writable place, to store its downloaded files.
# Mounts: input (data and settings file) and output directories
# 
# We call the gammalearn entrypoint directly in /opt/conda/bin, because micromamba is not initialized
# inside the container for a new user (and every user is new, since with apptainer the user remains the same
# as the user on the host system by default (only users defined in the containers are known))
apptainer run \
    --nv \
    --env "CUDA_VISIBLE_DEVICES=$CUDA_VISIBLE_DEVICES" \
    --env "NUMBA_CACHE_DIR=/tmp/NUMBA" \
    --env "CTAPIPE_CACHE=/tmp/CTAPIPE" \
    --mount type=bind,source=/path/to/input/data_dir/,destination=/corresponding/path/in/container/ \
	--mount type=bind,source=/path/to/output/data_dir/,destination=/corresponding/path/in/container/ \
     path_to_your_sif_file.sif uv run gammalearn path_to_your_experiment_settings.py

You can find examples of setting file in the examples and some sample data in example data

Contributing

Contributions are very much welcome: please see CONTRIBUTING.

Cite Us

Please cite

Jacquemont M, Vuillaume T, Benoit A, Maurin G, Lambert P, Lamanna G, Brill A. GammaLearn: A Deep Learning Framework for IACT Data. In36th International Cosmic Ray Conference (ICRC2019) 2019 Jul (Vol. 36, p. 705). DOI: https://doi.org/10.22323/1.358.0705

For reproducibility purposes, please also cite the exact version of GammaLearn you used by citing the corresponding DOI on Zenodo:

License

GammaLearn is distributed under an MIT license.

## Back to top