diff --git a/docs/source/installation/install.rst b/docs/source/installation/install.rst index 69df698fd..79ae57c41 100644 --- a/docs/source/installation/install.rst +++ b/docs/source/installation/install.rst @@ -1,29 +1,29 @@ .. 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 `_). +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 `_). - 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 @@ -31,38 +31,25 @@ Quick Start When installation is completed, you should be able to run `the 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 `_ 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 @@ -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 -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 @@ -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 `_. + +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 diff --git a/docs/source/installation/quick-start.html b/docs/source/installation/quick-start.html index 6c3fd2563..856b20a8a 100644 --- a/docs/source/installation/quick-start.html +++ b/docs/source/installation/quick-start.html @@ -57,12 +57,14 @@
+
GraphNeT
PyTorch
Your OS
CUDA
Run:
+
@@ -72,6 +74,11 @@