We recommend installing graphnet in a separate environment, e.g. using Anaconda (see details on installation here) or python virtual environment. This requires specifying a supported python version (see above) and ensuring that the C++ compilers (gcc) are up to date.
If you don't need to interface with IceTray (e.g., for reading data from I3 files or running inference on these), the following commands should provide a fast way to get up and running on most UNIX systems:
$ git clone [email protected]:<your-username>/graphnet.git
$ cd graphnet
$ conda create --name graphnet python=3.8 gcc_linux-64 gxx_linux-64 libgcc -y
$ conda activate graphnet
(graphnet) $ pip install -r requirements/torch_[gpu/cpu].txt -e .[develop,torch]This should allow you to e.g. run the scripts in examples/ out of the box. Here, we have installed recent C++ compilers using conda (gcc_linux-64 gxx_linux-64 libgcc), but if your system already have recent versions ($gcc --version should be > 5, at least) you should be able to omit these from the setup.
In some instances, you might want graphnet to be able to interface with IceTray, e.g., when converting I3 files to an intermediate file format for training GNN models(e.g., SQLite or parquet), as shown in the examples/convert_i3_to_sqlite.py script, or when running GNN inference as part of an IceTray chain. In these cases, you need to install graphnet in a python runtime that has IceTray installed.
To achieve this, we recommend running the following commands in a clean bash shell:
$ eval `/cvmfs/icecube.opensciencegrid.org/py3-v4.1.0/setup.sh`
$ /cvmfs/icecube.opensciencegrid.org/py3-v4.1.0/RHEL_7_x86_64/metaprojects/combo/stable/env-shell.shOptionally, you can alias these commands or save them as a bash script for convenience, as you will have to run these commands every time you want to use IceTray (with graphnet) in a clean shell.
With the IceTray environment active, you can now install graphnet at a user level. In the example below, we are installing a light-weight version of graphnet without the torch extras, i.e., without the machine learning packages (pytorch and pytorch-geometric). This is useful when you just want to convert data from I3 files to, e.g., SQLite, and won't be running inference on I3 files later on. In this case, you don't need to specify a requirements file, compared to the example below.
$ source cvmfs.sh
$ conda create --name graphnet_icetray
$ conda activate graphnet_icetray
$ pip install --user -e .[develop]This should allow you to run the examples/convert_i3_to_sqlite.py script with your preferred I3 files.
To make sure that the process of contributing is as smooth and effective as possible, we provide a few guidelines in the contributing guide that we encourage contributors to follow.
In short, everyone who wants to contribute to this project is more than welcome to do so! Contributions are handled through pull requests, that should be linked to a GitHub issue describing the feature to be added or bug to be fixed. Pull requests will be reviewed by the project maintainers and merged into the main branch when accepted.
We're using Weights & Biases (W&B) to track the results — i.e. losses, metrics, and model artifacts — of training runs as a means to track model experimentation and streamline optimisation. To authenticate with W&B, sign up on the website and run the following in your terminal after having installed this package:
$ wandb loginYou can use your own, personal projects on W&B, but for projects of common interest you are encouraged to join the graphnet-team team on W&B here, create new projects for your specific use cases, and log your runs there. Just ask @asogaard for an invite to the team!
If you don't want to use W&B and/or only want to log run data locally, you can run:
$ wandb offlineIf you change you mind, it's as simple as:
$ wandb onlineThe examples/train_model.py script shows how to train a model and log the results to W&B.