Skip to content

Commit 6b5608a

Browse files
RasmusOrsoeRasmusOrsoe
authored
Merge pull request #862 from RasmusOrsoe/update_installation_matrix
Update Installation Documentation & Matrix
2 parents 25f3c65 + 59ef6e9 commit 6b5608a

2 files changed

Lines changed: 140 additions & 75 deletions

File tree

‎docs/source/installation/install.rst‎

Lines changed: 88 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,85 @@
11
.. include:: ../substitutions.rst
2+
===========
3+
Quick Start
4+
===========
5+
Here we provide a quick start guide for getting you started with |graphnet|\ GraphNeT.
26

3-
Installation
4-
============
7+
Installing From Source
8+
======================
59

6-
|graphnet|\ GraphNeT is available for Python 3.9 to Python 3.11.
10+
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>`_).
11+
With conda installed, you can create a fresh environment like so
712

8-
.. note::
9-
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>`_).
10-
With conda installed, you can create a fresh environment like so
13+
.. code-block:: bash
1114
12-
.. code-block:: bash
15+
# Create the environment with minimal packages
16+
conda create --name graphnet_env --no-default-packages python=3.10
17+
conda activate graphnet_env
1318
14-
# Create the environment with minimal packages
15-
conda create --name graphnet_env --no-default-packages python=3.10
16-
conda activate graphnet_env
19+
# Update central packaging libraries
20+
pip install --upgrade setuptools packaging
1721
18-
# Update central packaging libraries
19-
pip install --upgrade setuptools packaging
20-
21-
# Verify that only wheel, packaging and setuptools are installed
22-
pip list
22+
# Verify that only wheel, packaging and setuptools are installed
23+
pip list
2324
24-
# Now you're ready to proceed with the installation
25-
Quick Start
26-
-----------
25+
# Now you're ready to proceed with the installation
26+
2727
2828
.. raw:: html
2929
:file: quick-start.html
3030

3131

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

34-
Installation in CVMFS (IceCube)
35-
-------------------------------
34+
Installation into experiment-specific Environments
35+
--------------------------------------------------
36+
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.
3637

37-
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.
38+
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.
3839

39-
To achieve this, we recommend installing |graphnet|\ GraphNeT into a CVMFS with IceTray installed, like so:
40+
IceTray (IceCube & P-ONE)
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
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.
43+
44+
Details on how to run these images as Apptainer environments are provided in the `Docker & Apptainer Images`_ section.
45+
46+
For users who prefer to install |graphnet|\ GraphNeT 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.
4047

4148
.. code-block:: bash
42-
49+
4350
# Download GraphNeT
4451
git clone https://github.com/graphnet-team/graphnet.git
4552
cd graphnet
53+
4654
# Open your favorite CVMFS distribution
4755
eval `/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/setup.sh`
4856
/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/RHEL_7_x86_64/metaprojects/icetray/v1.5.1/env-shell.sh
49-
# Update central utils
50-
pip install --upgrade 'pip>=20'
51-
pip install wheel setuptools==59.5.0
52-
# Install graphnet into the CVMFS as a user
53-
pip install --user -r requirements/torch_cpu.txt -e .[torch,develop]
5457
58+
# Upgrade central packaging libraries
59+
pip install --user --upgrade setuptools versioneer
5560
56-
Once installed, |graphnet|\ GraphNeT is available whenever you open the CVMFS locally.
61+
# Install PyTorch (CPU)
62+
pip3 install --user torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
5763
58-
Installation with km3io (KM3NeT)
59-
-----------------------------------------------
64+
# Install GraphNeT
65+
pip3 install --user -e .[torch-27,develop] -f https://data.pyg.org/whl/torch-2.7.0+cpu.html
6066
61-
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.
67+
To use |graphnet|\ GraphNeT in a new terminal session, re-activate the CVMFS distribution and the virtual environment:
6268

63-
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.
69+
.. code-block:: bash
6470
65-
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:
71+
eval `/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/setup.sh`
72+
/cvmfs/icecube.opensciencegrid.org/py3-v4.2.1/RHEL_7_x86_64/metaprojects/icetray/v1.5.1/env-shell.sh
73+
source ~/graphnet_venv/bin/activate
74+
python -c "import graphnet; print(graphnet.__version__)"
75+
76+
which should print the version of |graphnet|\ GraphNeT.
77+
78+
km3io (KM3NeT)
79+
~~~~~~~~~~~~~~~~
80+
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.
81+
82+
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:
6683

6784
.. code-block:: bash
6885
@@ -71,23 +88,23 @@ As mentioned, it is highly reommended to create a conda enviroment where your in
7188
# Activate the environment and move to the graphnet repository you just cloned. If using conda:
7289
conda activate <full-path-to-env>
7390
74-
The isntallation of GraphNeT is then done by:
91+
The installation of GraphNeT is then done by:
7592

7693
.. code-block:: bash
7794
7895
git clone https://github.com/graphnet-team/graphnet.git
7996
cd graphnet
8097
81-
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.
98+
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.
8299

83-
For CPU-only enviroments:
100+
For CPU-only environments:
84101

85102
.. code-block:: bash
86103
87104
pip3 install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cpu
88105
pip3 install -e .[torch-25] -f https://data.pyg.org/whl/torch-2.5.1+cpu.html
89106
90-
For GPU enviroments with, for instance, CUDA 11.8 drivers:
107+
For GPU environments with, for instance, CUDA 11.8 drivers:
91108

92109
.. code-block:: bash
93110
@@ -102,5 +119,36 @@ Downgrade setuptools for compatibility between km3io and GraphNeT.
102119
pip3 install km3io==1.2.0
103120
104121
105-
.. note::
106-
We recommend installing |graphnet|\ GraphNeT without GPU in clean metaprojects.
122+
Docker & Apptainer Images
123+
=========================
124+
125+
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.
126+
127+
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>`_.
128+
129+
In compliment to standalone images, we also provide experiment-specific images for:
130+
131+
- `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>`_.
132+
- KM3NeT (km3io+GraphNeT) (Coming Soon)
133+
134+
135+
136+
Running Docker images as Apptainer environments
137+
-----------------------------------------------
138+
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.
139+
140+
To run one of the Docker images as a Apptainer environment, you can use the following command:
141+
142+
.. code-block:: bash
143+
144+
apptainer exec --cleanenv --env PYTHONNOUSERSITE=1 --env PYTHONPATH= docker://<path_to_image> bash
145+
146+
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.
147+
148+
To run one of the images with IceTray+GraphNeT as a Apptainer environment, you can for example use the following command:
149+
150+
.. code-block:: bash
151+
152+
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
153+
154+
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.

‎docs/source/installation/quick-start.html‎

Lines changed: 52 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,14 @@
5757

5858
<div class="quick-start">
5959
<div class="title-column">
60+
<div>GraphNeT</div>
6061
<div>PyTorch</div>
6162
<div>Your OS</div>
6263
<div>CUDA</div>
6364
<div>Run:</div>
6465
</div>
6566
<div class="content-column">
67+
<div class="row" id="graphnet"></div>
6668
<div class="row" id="torch"></div>
6769
<div class="row" id="os"></div>
6870
<div class="row" id="cuda"></div>
@@ -72,6 +74,11 @@
7274

7375
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
7476
<script>
77+
var graphnetList = [
78+
['v1.8.0', 'v1.8.0 (Stable)'],
79+
['latest', 'Latest'],
80+
];
81+
7582
var torchList = [
7683
['torch-2.7.0', 'PyTorch 2.7.0'],
7784
['torch-2.6.0', 'PyTorch 2.6.0'],
@@ -105,6 +112,10 @@
105112
"torch-2.5.1": "torch-25"
106113
};
107114

115+
for (var i = 0; i < graphnetList.length; i++) {
116+
$("#graphnet").append('<div id="' + graphnetList[i][0] + '">' + graphnetList[i][1] + '</div>');
117+
}
118+
108119
for (var i = 0; i < torchList.length; i++) {
109120
$("#torch").append('<div id="' + torchList[i][0] + '">' + torchList[i][1] + '</div>');
110121
}
@@ -123,42 +134,53 @@
123134
}
124135

125136
function updateCommand() {
126-
var torch = $("#command").attr("torch");
127-
var os = $("#command").attr("os");
128-
var cuda = $("#command").attr("cuda");
137+
var graphnet = $("#command").attr("graphnet");
138+
var torch = $("#command").attr("torch");
139+
var os = $("#command").attr("os");
140+
var cuda = $("#command").attr("cuda");
129141

130-
if (!torch || !os || !cuda) return;
142+
if (!graphnet || !torch || !os || !cuda) return;
131143

132-
if (os === "macos" && cuda !== "cpu") {
133-
$("#command pre").text('# macOS binaries do not support CUDA');
134-
return;
135-
}
144+
if (os === "macos" && cuda !== "cpu") {
145+
$("#command pre").text('# macOS binaries do not support CUDA');
146+
return;
147+
}
136148

137-
if (cuda !== "cpu" && torch === "no_torch") {
138-
$("#command pre").text('# GPU acceleration is not available without PyTorch.');
139-
return;
140-
}
149+
if (cuda !== "cpu" && torch === "no_torch") {
150+
$("#command pre").text('# GPU acceleration is not available without PyTorch.');
151+
return;
152+
}
141153

142-
if (
143-
(torch === "torch-2.7.0" && (cuda === "cu121" || cuda === "cu124")) ||
144-
(torch === "torch-2.6.0" && (cuda === "cu121" || cuda === "cu128")) ||
145-
(torch === "torch-2.5.1" && (cuda === "cu126" || cuda === "cu128"))
146-
) {
147-
$("#command pre").text('# PyTorch version does not support CUDA ' + formatCudaLabel(cuda));
148-
return;
149-
}
154+
if (
155+
(torch === "torch-2.7.0" && (cuda === "cu121" || cuda === "cu124")) ||
156+
(torch === "torch-2.6.0" && (cuda === "cu121" || cuda === "cu128")) ||
157+
(torch === "torch-2.5.1" && (cuda === "cu126" || cuda === "cu128"))
158+
) {
159+
$("#command pre").text('# PyTorch version does not support CUDA ' + formatCudaLabel(cuda));
160+
return;
161+
}
162+
163+
var gitCloneCmd =
164+
graphnet === "v1.8.0"
165+
? "git clone --branch v1.8.0 --depth 1 https://github.com/graphnet-team/graphnet.git"
166+
: "git clone https://github.com/graphnet-team/graphnet.git";
167+
168+
if (torch === "no_torch") {
169+
$("#command pre").text([
170+
"# Clone and Install GraphNeT",
171+
gitCloneCmd,
172+
"cd graphnet",
173+
"pip3 install -e .[develop]"
174+
].join("\n"));
175+
return;
176+
}
150177

151-
if (torch === "no_torch") {
152-
$("#command pre").text("pip3 install -e .[develop]");
153-
} else {
154178
var torchVersion = torchWheelMap[torch];
155179
var extrasPrefix = torchExtrasMap[torch];
156-
157180
var installLine = "pip3 install -e .[" + extrasPrefix + "]";
158181
var wheelUrl = "https://data.pyg.org/whl/torch-" + torchVersion + "+" + (cuda === "cpu" ? "cpu" : cuda) + ".html";
159182
installLine += " -f " + wheelUrl;
160183

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

183-
// Pick PyTorch install command or fallback to cpu
184-
var pytorchCmd = pytorchInstallCommands[torch][cuda];
185-
if (!pytorchCmd) {
186-
pytorchCmd = pytorchInstallCommands[torch]["cpu"] || "pip3 install torch torchvision torchaudio";
187-
}
205+
var pytorchCmd = pytorchInstallCommands[torch][cuda] ||
206+
pytorchInstallCommands[torch]["cpu"];
188207

189208
$("#command pre").text([
190-
"# Install PyTorch ",
209+
"# Install PyTorch",
191210
pytorchCmd,
192211
" ",
193212
"# Clone and Install GraphNeT",
194-
"git clone https://github.com/graphnet-team/graphnet.git",
213+
gitCloneCmd,
195214
"cd graphnet",
196215
installLine,
197216
" ",
198217
"# Optionally, install jammy_flows for normalizing flow support:",
199218
"pip3 install git+https://github.com/thoglu/jammy_flows.git"
200219
].join("\n"));
201220
}
202-
}
203-
204221

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

212-
// Default selection
229+
$("#graphnet").children().get(0).click();
213230
$("#torch").children().get(0).click();
214231
$("#linux").click();
215232
$("#cpu").click();

0 commit comments

Comments
 (0)