Skip to content

Update Installation Documentation & Matrix #862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RasmusOrsoe wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update Installation Documentation & Matrix #862

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
82e2122
update installation matrix and installation documentation
RasmusOrsoe Jan 8, 2026
40ba58b
Update instalation matrix
RasmusOrsoe Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 67 additions & 49 deletions docs/source/installation/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,55 @@
.. include:: ../substitutions.rst
===========
Quick Start
===========
Here we provide a quick start guide for getting you started with |graphnet|\ GraphNeT.

Installation
============
Installing From Source
======================

|graphnet|\ GraphNeT is available for Python 3.9 to Python 3.11.
We recommend installing |graphnet|\ GraphNeT in a separate environment, e.g. using a Python virtual environment or Anaconda (see details on installation `here <https://www.anaconda.com/products/individual>`_).
With conda installed, you can create a fresh environment like so

.. note::
We recommend installing |graphnet|\ GraphNeT in a separate environment, e.g. using a Python virtual environment or Anaconda (see details on installation `here <https://www.anaconda.com/products/individual>`_).
With conda installed, you can create a fresh environment like so
.. code-block:: bash

.. code-block:: bash
# Create the environment with minimal packages
conda create --name graphnet_env --no-default-packages python=3.10
conda activate graphnet_env

# 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

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

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

# Now you're ready to proceed with the installation
Quick Start
-----------
# Now you're ready to proceed with the installation


.. raw:: html
:file: quick-start.html


When installation is completed, you should be able to run `the examples <https://github.com/graphnet-team/graphnet/tree/main/examples>`_.

Installation in CVMFS (IceCube)
-------------------------------
Installation into experiment-specific Environments
--------------------------------------------------
Users may want to install |graphnet|\ GraphNeT 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.

You may want |graphnet|\ GraphNeT to be able to interface with IceTray, e.g., when converting I3 files to a deep learning friendly file format, or when deploying models as part of an IceTray chain. In these cases, you need to install |graphnet|\ GraphNeT in a Python runtime that has IceTray installed.
Below are some examples of how to install |graphnet|\ GraphNeT into experiment-specific environments. If your experiment is missing, please feel free to open an issue on the `GitHub repository <https://github.com/graphnet-team/graphnet/issues>`_ and/or contribute a pull request.

To achieve this, we recommend installing |graphnet|\ GraphNeT into a CVMFS with IceTray installed, like so:

.. code-block:: bash

# 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
# Update central utils
pip install --upgrade 'pip>=20'
pip install wheel setuptools==59.5.0
# Install graphnet into the CVMFS as a user
pip install --user -r requirements/torch_cpu.txt -e .[torch,develop]
IceTray (IceCube & P-ONE)
~~~~~~~~~~~~~~~~~~~~~~~~~~
While |graphnet|\ GraphNeT 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.

Once installed, |graphnet|\ GraphNeT is available whenever you open the CVMFS locally.

Installation with km3io (KM3NeT)
-----------------------------------------------

This installation is only necessary if you want to process KM3NeT/ARCA or KM3NeT/ORCA files. Processing means converting them from a `.root` offline format into a suitable format for training using |graphnet|. If you already have your KM3NeT data in `SQLite` or `parquet` format and only want to train a model or perform inference on this database, this specific installation is not needed.

Note that this installation will add `km3io` ensuring it is built with a compatible versions. The steps below are provided for a conda environment, with an enviroment created in the same way it is done above in this page, but feel free to choose a different enviroment setup.
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 reommended to create a conda enviroment where your installation is done to do not mess up any dependecy. It can be done with the following commands:
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:

.. code-block:: bash

Expand All @@ -71,23 +58,23 @@ As mentioned, it is highly reommended to create a conda enviroment where your in
# Activate the environment and move to the graphnet repository you just cloned. If using conda:
conda activate <full-path-to-env>

The isntallation of GraphNeT is then done by:
The installation of GraphNeT is then done by:

.. code-block:: bash

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 can be installed.
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 enviroments:
For CPU-only environments:

.. code-block:: bash

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 enviroments with, for instance, CUDA 11.8 drivers:
For GPU environments with, for instance, CUDA 11.8 drivers:

.. code-block:: bash

Expand All @@ -102,5 +89,36 @@ Downgrade setuptools for compatibility between km3io and GraphNeT.
pip3 install km3io==1.2.0


.. note::
We recommend installing |graphnet|\ GraphNeT without GPU in clean metaprojects.
Docker & Apptainer Images
=========================

We provide Docker images for |graphnet|\ GraphNeT. 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 <https://github.com/graphnet-team/graphnet/blob/main/docker/standalone/Dockerfile>`_.

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

- `IceCube & P-ONE (IceTray+GraphNeT) <https://hub.docker.com/r/rorsoe/graphnet_icetray/tags>`_ which is built using this `Dockerfile <https://github.com/graphnet-team/graphnet/blob/main/docker/icetray/Dockerfile>`_.
- KM3NeT (km3io+GraphNeT) (Coming Soon)



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 |graphnet|\ GraphNeT 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:

.. code-block:: bash

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:

.. code-block:: bash

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.
87 changes: 52 additions & 35 deletions docs/source/installation/quick-start.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,14 @@

<div class="quick-start">
<div class="title-column">
<div>GraphNeT</div>
<div>PyTorch</div>
<div>Your OS</div>
<div>CUDA</div>
<div>Run:</div>
</div>
<div class="content-column">
<div class="row" id="graphnet"></div>
<div class="row" id="torch"></div>
<div class="row" id="os"></div>
<div class="row" id="cuda"></div>
Expand All @@ -72,6 +74,11 @@

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script>
var graphnetList = [
['v1.8.0', 'v1.8.0 (Stable)'],
['latest', 'Latest'],
];

var torchList = [
['torch-2.7.0', 'PyTorch 2.7.0'],
['torch-2.6.0', 'PyTorch 2.6.0'],
Expand Down Expand Up @@ -105,6 +112,10 @@
"torch-2.5.1": "torch-25"
};

for (var i = 0; i < graphnetList.length; i++) {
$("#graphnet").append('<div id="' + graphnetList[i][0] + '">' + graphnetList[i][1] + '</div>');
}

for (var i = 0; i < torchList.length; i++) {
$("#torch").append('<div id="' + torchList[i][0] + '">' + torchList[i][1] + '</div>');
}
Expand All @@ -123,42 +134,53 @@
}

function updateCommand() {
var torch = $("#command").attr("torch");
var os = $("#command").attr("os");
var cuda = $("#command").attr("cuda");
var graphnet = $("#command").attr("graphnet");
var torch = $("#command").attr("torch");
var os = $("#command").attr("os");
var cuda = $("#command").attr("cuda");

if (!torch || !os || !cuda) return;
if (!graphnet || !torch || !os || !cuda) return;

if (os === "macos" && cuda !== "cpu") {
$("#command pre").text('# macOS binaries do not support CUDA');
return;
}
if (os === "macos" && cuda !== "cpu") {
$("#command pre").text('# macOS binaries do not support CUDA');
return;
}

if (cuda !== "cpu" && torch === "no_torch") {
$("#command pre").text('# GPU acceleration is not available without PyTorch.');
return;
}
if (cuda !== "cpu" && torch === "no_torch") {
$("#command pre").text('# GPU acceleration is not available without PyTorch.');
return;
}

if (
(torch === "torch-2.7.0" && (cuda === "cu121" || cuda === "cu124")) ||
(torch === "torch-2.6.0" && (cuda === "cu121" || cuda === "cu128")) ||
(torch === "torch-2.5.1" && (cuda === "cu126" || cuda === "cu128"))
) {
$("#command pre").text('# PyTorch version does not support CUDA ' + formatCudaLabel(cuda));
return;
}
if (
(torch === "torch-2.7.0" && (cuda === "cu121" || cuda === "cu124")) ||
(torch === "torch-2.6.0" && (cuda === "cu121" || cuda === "cu128")) ||
(torch === "torch-2.5.1" && (cuda === "cu126" || cuda === "cu128"))
) {
$("#command pre").text('# PyTorch version does not support CUDA ' + formatCudaLabel(cuda));
return;
}

var gitCloneCmd =
graphnet === "v1.8.0"
? "git clone --branch v1.8.0 --depth 1 https://github.com/graphnet-team/graphnet.git"
: "git clone https://github.com/graphnet-team/graphnet.git";

if (torch === "no_torch") {
$("#command pre").text([
"# Clone and Install GraphNeT",
gitCloneCmd,
"cd graphnet",
"pip3 install -e .[develop]"
].join("\n"));
return;
}

if (torch === "no_torch") {
$("#command pre").text("pip3 install -e .[develop]");
} else {
var torchVersion = torchWheelMap[torch];
var extrasPrefix = torchExtrasMap[torch];

var installLine = "pip3 install -e .[" + extrasPrefix + "]";
var wheelUrl = "https://data.pyg.org/whl/torch-" + torchVersion + "+" + (cuda === "cpu" ? "cpu" : cuda) + ".html";
installLine += " -f " + wheelUrl;

// --- Added PyTorch wheels install command here ---
var pytorchInstallCommands = {
"torch-2.5.1": {
"cu118": "pip3 install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118",
Expand All @@ -180,27 +202,22 @@
}
};

// Pick PyTorch install command or fallback to cpu
var pytorchCmd = pytorchInstallCommands[torch][cuda];
if (!pytorchCmd) {
pytorchCmd = pytorchInstallCommands[torch]["cpu"] || "pip3 install torch torchvision torchaudio";
}
var pytorchCmd = pytorchInstallCommands[torch][cuda] ||
pytorchInstallCommands[torch]["cpu"];

$("#command pre").text([
"# Install PyTorch ",
"# Install PyTorch",
pytorchCmd,
" ",
"# Clone and Install GraphNeT",
"git clone https://github.com/graphnet-team/graphnet.git",
gitCloneCmd,
"cd graphnet",
installLine,
" ",
"# Optionally, install jammy_flows for normalizing flow support:",
"pip3 install git+https://github.com/thoglu/jammy_flows.git"
].join("\n"));
}
}


$(".quick-start .content-column .row div").click(function () {
$(this).parent().children().removeClass("selected");
Expand All @@ -209,7 +226,7 @@
updateCommand();
});

// Default selection
$("#graphnet").children().get(0).click();
$("#torch").children().get(0).click();
$("#linux").click();
$("#cpu").click();
Expand Down