diff --git a/docs/source/installation/install.rst b/docs/source/installation/install.rst index 165cb3bb1..3d33622dd 100644 --- a/docs/source/installation/install.rst +++ b/docs/source/installation/install.rst @@ -4,9 +4,48 @@ Quick Start =========== Here we provide a quick start guide for getting you started with |graphnet|\ GraphNeT. +The easiest way to get started is with our pre-built Docker images — see `Docker & Apptainer Images`_ below. They ship GraphNeT, PyTorch and (optionally) IceTray ready to use, with both CPU and GPU variants, and can be run without sudo via Apptainer. If you instead need a writable install or an environment without a container runtime, see `Installing From Source`_. + +Docker & Apptainer Images +========================= + +We provide Docker images for |graphnet|\ GraphNeT — this is the recommended way to get started. The list of available 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: + +- `IceCube & P-ONE (IceTray+GraphNeT) `_ which is built using this `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. This is the standard path on HPC clusters. + +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:// bash + +where 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. + + Installing From Source ====================== +If the Docker/Apptainer images above do not fit your use case — for example, you need a writable, editable install for development, or you cannot run a container runtime on your system — you can install |graphnet|\ GraphNeT from source. + We recommend installing |graphnet|\ GraphNeT 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 @@ -20,10 +59,10 @@ With conda installed, you can create a fresh environment like so pip install --upgrade setuptools packaging # Verify that only wheel, packaging and setuptools are installed - pip list + pip list # Now you're ready to proceed with the installation - + .. raw:: html :file: quick-start.html @@ -39,9 +78,7 @@ Below are some examples of how to install |graphnet|\ GraphNeT into experiment-s 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. +For IceTray-based workflows we strongly recommend the `IceCube & P-ONE (IceTray+GraphNeT) `_ Docker images covered in the section above — they bundle a known-good IceTray + GraphNeT combination and avoid the version-pinning issues that come with installing GraphNeT into an existing IceTray environment. 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. @@ -117,38 +154,4 @@ 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 |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 `_. - -In compliment to standalone images, we also provide experiment-specific images for: - -- `IceCube & P-ONE (IceTray+GraphNeT) `_ which is built using this `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:// bash - -where 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. \ No newline at end of file