README.md

metadata

title: HitPF
emoji: ⚛️
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false

HitPF

HitPF is a GATr-based particle-flow reconstruction model for the CLD detector at the FCC-ee. It performs two sequential tasks:

1. Clustering — groups calorimeter hits and tracks into particle-flow objects using an object-condensation loss.
2. Property regression — regresses a correction factor for each reconstructed cluster using a GNN-based model and a PID class

---

Dependencies

The code can be used with this container: docker://dologarcia/gatr:v9

For the live demo, gradio and plotly also need to be installed:

pip install gradio plotly

---

Dataset

Input data is stored as .parquet files, each file stores 100 events. A sample of the dataset in ML-ready format can be found at 1. The full dataset is hosted on CERN's EOS space.

---

Training

Step 1 — Clustering

bash scripts/train_clustering.sh

Step 2 — Energy correction

bash scripts/train_energy_pid.sh

Validation

bash scripts/evaluation.sh

---

Live demo (work in progress)

python -m app

Citation

If you use this code, please cite:

@software{hitpf2026,
  title  = {End-to-end event reconstruction for precision physics at future colliders code},
  year   = {2026},
  url    = {https://github.com/mgarciam/HitPF}
}