HyPER

Documentation

HyPER (Hypergraph for Particle Event Reconstruction) is Graph Neural Network (GNN) utilising blended graph-hypergraph representation learning to reconstruct short-lived particles from their complex final states.

• Quick Start
• Enviroment

Quick Start

We have removed graph building precedure following #4. GraphDataset now loads flat data from a HDF5 file and computes graph structure on the fly. We are no longer recommand and provide support to release v0.1.

Network training

HyPER model is built upon pytorch_lightning, which uses tensorboard logger to save trained models.

To train HyPER:

python -m HyPER.train --config-name=default [options]

HyPER uses hydra for configuring run (#10). You can overwrite any option using, for example, all_matched=False at the end, it overwrites the all_matched option provided in your configuration file.

Configuration files must be placed in the configs folder. Provide the file name without .yaml extension to --config-name.

Evaluation

To evaluate trained HyPER model on a dataset:

python -m HyPER.predict --config-name=default [options]

Four output variables are saved:

Based on these RAW outputs, events can then be reconstructed by stating the correct topology in the configuration file. We currently have limited event topologies available in HyPER, see HyPER/topology. If you wish additional ones to be added, you can create a issue here.

Enviroment

Currenlty, conda auto environment solving is only supported by Linux/amd64 machines, due to some ongoing issues with torch_geometric in MacOS. A conda environment file environment_linux.yml is provided. We recommend using miniforge as your conda package manager due to its lightweightness.

To create a conda environment named "HyPER":

conda env create -f environment_linux.yml

We have tested the code with CUDA=11.8, HyPER should work with any CUDA versions above.