Quick Start

Here we provide a quick start guide for getting you started with graphnetGraphNeT.

Installing From Source

We recommend installing graphnetGraphNeT in a separate environment, e.g. using a Python virtual environment or Anaconda (see details on installation here). With conda installed, you can create a fresh environment like so

# Create the environment with minimal packages
conda create --name graphnet_env --no-default-packages python=3.10
conda activate graphnet_env

# Update central packaging libraries
pip install --upgrade setuptools packaging

# Verify that only wheel, packaging and setuptools are installed
pip list

# Now you're ready to proceed with the installation
GraphNeT
PyTorch
Your OS
CUDA
Run:








When installation is completed, you should be able to run the examples.




Installation into experiment-specific Environments


Users may want to install graphnetGraphNeT into an environment that is specific to their experiment. This is useful for converting data from the experiment into a deep learning friendly file format, or when deploying models as part of an experiment-specific processing chain.


Below are some examples of how to install graphnetGraphNeT into experiment-specific environments. If your experiment is missing, please feel free to open an issue on the GitHub repository and/or contribute a pull request.




IceTray (IceCube & P-ONE)


While graphnetGraphNeT can be installed into existing IceTray environments that is either built from source or distributed through CVMFS, we highly recommend to instead use our existing Docker images that contain both IceTray and GraphNeT. These images are created by installing GraphNeT into public Docker images from the IceCube Collaboration.


Details on how to run these images as Apptainer environments are provided in the Docker & Apptainer Images section.


For users who prefer to install graphnetGraphNeT directly into a CVMFS environment rather than using Docker/Apptainer images, you can follow the steps below. This example uses PyTorch 2.7.0 (CPU) — adjust the PyTorch version and extras according to the compatibility matrix above.


# Download GraphNeT
git clone https://github.com/graphnet-team/graphnet.git
cd graphnet

# Open your favorite CVMFS distribution
eval `/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/setup.sh`
/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/RHEL_7_x86_64/metaprojects/icetray/v1.5.1/env-shell.sh

# Upgrade central packaging libraries
pip install --user --upgrade setuptools versioneer

# Install PyTorch (CPU)
pip3 install --user torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# Install GraphNeT
pip3 install --user -e .[torch-27,develop] -f https://data.pyg.org/whl/torch-2.7.0+cpu.html





To use graphnetGraphNeT in a new terminal session, re-activate the CVMFS distribution and the virtual environment:


eval `/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/setup.sh`
/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/RHEL_7_x86_64/metaprojects/icetray/v1.5.1/env-shell.sh
source ~/graphnet_venv/bin/activate
python -c "import graphnet; print(graphnet.__version__)"





which should print the version of graphnetGraphNeT.






km3io (KM3NeT)


Note that this installation will add km3io ensuring it is built with a compatible version. The steps below are provided for a conda environment, with an environment created in the same way it is done above in this page, but feel free to choose a different environment setup.


As mentioned, it is highly recommended to create a conda environment where your installation is done to do not mess up any dependency. It can be done with the following commands:


# Create an environment with Python 3.10
conda create -p <full-path-to-env> --no-default-packages python=3.10 -y
# Activate the environment and move to the graphnet repository you just cloned. If using conda:
conda activate <full-path-to-env>





The installation of GraphNeT is then done by:


git clone https://github.com/graphnet-team/graphnet.git
cd graphnet





Choose the appropriate requirements file based on your system. Here there is just an example of installation with PyTorch-2.5.1 but check the matrix above for a full idea of all the versions that can be installed.


For CPU-only environments:


pip3 install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cpu
pip3 install -e .[torch-25] -f https://data.pyg.org/whl/torch-2.5.1+cpu.html





For GPU environments with, for instance, CUDA 11.8 drivers:


pip3 install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118
pip3 install -e .[torch-25] -f https://data.pyg.org/whl/torch-2.5.1+cu118.html





Downgrade setuptools for compatibility between km3io and GraphNeT.


pip3 install --force-reinstall setuptools==70.3.0
pip3 install km3io==1.2.0













Docker & Apptainer Images


We provide Docker images for graphnetGraphNeT. The list of available Docker images with standalone installations of GraphNeT can be found in DockerHub at https://hub.docker.com/r/rorsoe/graphnet/tags.


New images are created automatically when a new release is published, and when a new PR is merged to the main branch (latest). Each image comes in both GPU and CPU versions, but with a limited selection of pytorch versions. The Dockerfile for the standalone images is here.


In compliment to standalone images, we also provide experiment-specific images for:





Running Docker images as Apptainer environments


While Docker images require sudo-rights to run, they may be converted to Apptainer images and used as virtual environments - providing a convienient way to run graphnetGraphNeT without sudo-rights or the need to install it on your system.


To run one of the Docker images as a Apptainer environment, you can use the following command:


apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://<path_to_image> bash





where <path_to_image> is the path to the image you want to use from the DockerHub. For example, if rorsoe/graphnet:graphnet-1.8.0-cu126-torch26-ubuntu-22.04 is chosen, an image with GraphNeT 1.8.0 + PyTorch 2.6.0 + CUDA 12.6 installed will open. The additional arguments –cleanenv –env PYTHONNOUSERSITE=1 –env PYTHONPATH= ensure that the environment is not contaminated with any other packages that may be installed on your system.


To run one of the images with IceTray+GraphNeT as a Apptainer environment, you can for example use the following command:


apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://rorsoe/graphnet_icetray:graphnet-1.8.0-cpu-torch26-icecube-icetray-icetray-devel-v1.13.0-ubuntu22.04-2025-02-12 bash





which opens an image with a CPU-installation of GraphNeT 1.8.0 + PyTorch v2.6.0 + IceTray v1.13.0 installed and ready to use. You can replace the image path with the one you want to use from the DockerHub.