Metadata-Version: 2.4
Name: gammalearn
Version: 0.16.0
Summary: A framework to easily train deep learning model on Imaging Atmospheric Cherenkov Telescopes data
Author-email: "M. Jacquemont" <jacquemont@lapp.in2p3.fr>, "T. Vuillaume" <thomas.vuillaume@lapp.in2p3.fr>
License-Expression: MIT
Project-URL: Homepage, https://gammalearn.pages.in2p3.fr/pages/
Project-URL: Repository, https://gitlab.in2p3.fr/gammalearn/gammalearn
Project-URL: Documentation, https://gammalearn.pages.in2p3.fr/gammalearn/
Project-URL: Issues, https://gitlab.in2p3.fr/gammalearn/gammalearn/-/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: astropy<8.0.0,>=6.1.7
Requires-Dist: ctapipe<0.26.0,>=0.25.1
Requires-Dist: ctaplot<0.7.0,>=0.6.5
Requires-Dist: dl1-data-handler
Requires-Dist: h5py<4.0.0,>=3.15.0
Requires-Dist: indexedconv<2.0.0,>=1.3.2
Requires-Dist: lightning<3.0.0,>=2.6.1
Requires-Dist: lstchain<0.12.0,>=0.11.3
Requires-Dist: matplotlib<4.0.0,>=3.10.8
Requires-Dist: numpy<2.4.0,>=2.1.0
Requires-Dist: pandas<3.0.0,>=2.3.3
Requires-Dist: pillow<13.0.0,>=12.1.1
Requires-Dist: pot<0.10.0,>=0.9.6.post1
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: scikit-image<0.27.0,>=0.20.0
Requires-Dist: tables<4.0.0,>=3.11.1
Requires-Dist: tensorboardx<3.0.0,>=2.6.2.2
Requires-Dist: torchmetrics<2.0.0,>=1.8.2
Requires-Dist: tqdm<5.0.0,>=4.67.3
Requires-Dist: wandb<0.26.0,>=0.25.0
Provides-Extra: cpu
Requires-Dist: torch<3.0.0,>=2.9.1; extra == "cpu"
Requires-Dist: torchvision<1.0.0,>=0.24.1; extra == "cpu"
Provides-Extra: gpu
Requires-Dist: torch<3.0.0,>=2.9.1; extra == "gpu"
Requires-Dist: torchvision<1.0.0,>=0.24.1; extra == "gpu"

# GammaLearn

<p align="left">
<img src="https://gammalearn.pages.in2p3.fr/pages/images/glearn.png" width="60px" >
<b><i>Deep Learning for Imaging Cherenkov Telescopes Data Analysis.</b></i>
</p>

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.


[![](https://img.shields.io/badge/GammaLearn-Pages-yellow)](https://purl.org/gammalearn)
[![](https://img.shields.io/badge/GammaLearn-Code-blue)](https://gitlab.in2p3.fr/gammalearn/gammalearn)
[![](https://img.shields.io/badge/GammaLearn-Documentation-orange)](https://gammalearn.pages.in2p3.fr/gammalearn)
[![](https://img.shields.io/badge/GammaLearn-Slack-green)](https://gammalearn.slack.com/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5879803.svg)](https://doi.org/10.5281/zenodo.5879803)

[![pipeline status](https://gitlab.in2p3.fr//gammalearn/gammalearn/badges/master/pipeline.svg)](https://gitlab.in2p3.fr//gammalearn/gammalearn/-/commits/master)
[![coverage report](https://gitlab.in2p3.fr/gammalearn/gammalearn/badges/master/coverage.svg)](https://gammalearn.pages.in2p3.fr/gammalearn/htmlcov)

## Table of Contents


1. [Installation](#installation)
2. [Usage](#usage)
3. [Contributing](#contributing)
4. [Cite Us](#cite-us)
5. [License](#license)


## Installation

### For users

GammaLearn uses `uv` to manage environments and dependencies.


### Quick start (local installation)

### Prerequisites

Install uv if needed:
```bash
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):
```bash
uv init && uv add gammalearn --extra cpu
```
or
```bash
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:
```bash
git clone https://gitlab.in2p3.fr/gammalearn/gammalearn.git
cd gammalearn
```
Install dependencies using uv:


```
uv sync --extra cpu
```
For GPU environments:
```bash

uv sync --extra gpu
```

Run GammaLearn:
```bash
uv run gammalearn --help
```

Run tests:
```bash
uv run --locked --extra cpu --group test pytest
```

**Note:** If dependencies are modified, update the lock file before committing:
```bash
uv lock
```

### Development with Docker (alternative to local uv setup)

The published `gammalearn/prod` image (used to [run experiments](#run-an-experiment-production)) is a minimal
multistage build that intentionally does not include `uv` and installs gammalearn non-editably, so it isn't
suitable for development. Instead, build a development container from the `builder` stage of
[`docker/Dockerfile`](https://gitlab.in2p3.fr/gammalearn/gammalearn/-/blob/master/docker/Dockerfile), which still has `uv`, Python, and the build tools (`git`, `gcc`, `g++`)
needed to compile some dependencies, and mount your working copy over it so gammalearn is installed in editable
mode from your local sources.

Clone gammalearn locally and go in the gammalearn directory:
```bash
git clone https://gitlab.in2p3.fr/gammalearn/gammalearn.git && cd gammalearn
```

#### Usage with an IDE (vscode example)

Many IDE's offer the possibility to build and interact with development containers. In VScode, this is handled by
the "dev container" extension included in the remote development extension pack (see the extension
[documentation](https://code.visualstudio.com/docs/devcontainers/containers)). The extension can build a container
from a Dockerfile and automatically install a vs-code server inside it, allowing to transparently develop the
software while using the environment from inside the container. Add the following as
`.devcontainer/devcontainer.json`: it builds the `builder` stage of `docker/Dockerfile`, mounts your working copy
at `/gammalearn` (the same path the image already uses as its `WORKDIR`), and installs gammalearn plus the `dev`
dependency group (lint, test, doc) in editable mode from those mounted sources. As examples, the python extension
and ruff linter are installed in the vs-code server running in the container.

```json
// For format details, see https://aka.ms/devcontainer.json
{
	"build": {
		"dockerfile": "../docker/Dockerfile",
		"target": "builder"
	},
	"workspaceMount": "source=${localWorkspaceFolder},target=/gammalearn,type=bind",
	"workspaceFolder": "/gammalearn",
	"postCreateCommand": "uv sync --extra cpu --group dev",
	"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"
			]
		}
	}
}
```

Use `--extra gpu` instead of `--extra cpu` in `postCreateCommand` if you need GPU support in the container (`cpu` and `gpu` are declared as mutually exclusive extras, so pass only one).

Note: By default, the dev containers extension will not rebuild the image unless you explicitly rebuild the container in vscode, so pull the latest changes to `docker/Dockerfile` and rebuild if it has changed.

Once the container is running, you can enter it from another external terminal with
```bash
# Get the container ID of your dev container started with vscode
docker ps
# Get a shell in the container
docker exec -it -w /gammalearn container_ID bash
```

## Usage
### Run an experiment (Production)

We recommend the use of [apptainer](https://apptainer.org/). 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`:
```bash
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:
```bash
apptainer run path_to_your_sif_file.sif bash -c "source /gammalearn/.venv/bin/activate && 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:

```bash
# 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 source the venv's activate script (the venv is at /gammalearn/.venv in the image) rather than
# relying on the image's PATH or on `uv run`, because: the published image does not include `uv` at
# all (it's stripped in the final build stage to save space), and apptainer does not reliably apply
# the image's declared PATH for a new user (every user is "new" under apptainer, since the container
# user is always mapped to the host user rather than a user defined in the image).
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 bash -c "source /gammalearn/.venv/bin/activate && gammalearn path_to_your_experiment_settings.py"
```

You can find examples of setting file in the [examples](https://gitlab.in2p3.fr/gammalearn/gammalearn/-/tree/master/gammalearn/configuration/examples) and some sample data in [example data](https://gitlab.in2p3.fr/gammalearn/gammalearn/-/tree/master/share/data)


## Contributing

Contributions are very much welcome: please see [CONTRIBUTING](https://gitlab.in2p3.fr/gammalearn/gammalearn/-/blob/master/CONTRIBUTING.md).


## 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](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:  
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5879803.svg)](https://doi.org/10.22323/1.358.0705)


## License

GammaLearn is distributed under an [MIT license](https://gitlab.in2p3.fr/gammalearn/gammalearn/-/blob/master/LICENSE).

## [Back to top](#table-of-contents)
