MLPF reconstructs the particles produced in a collision from detector measurements. It uses a neural network to combine information from tracking detectors and calorimeters and produces a list of particle candidates for the full event. The project supports studies with the CMS detector and with the CLD and CLIC future-detector concepts.
This documentation describes the codebase prepared for v3.2.0: supported workflows, configuration, and validation limits. Dataset schemas and model artifacts have independent versions. Published physics results remain tied to their original code, data, detector setup, and checkpoints.
Where should I start?¶
| If you want to... | Start here |
|---|---|
| Understand particle flow and MLPF | Particle flow and MLPF |
| Check that the repository works | Quickstart |
| Choose between evaluation, training, and data production | Choose a workflow |
| Download a prepared training dataset | Dataset download |
| Produce a dataset from simulation | Dataset generation |
| Train or continue a model | Train a model |
| Balance training samples and monitor their losses | Dataset mixing |
| Evaluate a published CLD or CLIC model | Key4HEP evaluation |
| Choose the right validation check | Validation overview |
| Export and compare an ONNX model | ONNX validation |
| See which detectors and features are implemented | Current capabilities |
| Read the scientific results | Publications |
| Understand remaining limits and priorities | Development priorities |
| Find a code component | Repository map |
The workflow at a glance¶
detector simulation
|
v
tracks, calorimeter clusters, or detector hits
|
v
detector-specific postprocessing and data checks
|
v
versioned TensorFlow Dataset (TFDS)
|
v
MLPF training and checkpoint
|
v
particle predictions
|
v
particle, jet, missing-momentum, and deployment validationThe full workflow is available for CMS, CLD, and CLIC. Published datasets and model checkpoints from the MLPF Hugging Face repositories provide the shortest starting path.
For a first hands-on use, download the published CLD dataset and follow the short training path. For an existing checkpoint, start with the standalone Key4HEP evaluator.
Support levels¶
The documentation uses four labels:
Supported: there is a maintained configuration and a tested path in this repository.
Research workflow: the implementation is usable, but it needs more detector, model, or computing knowledge.
Partial: an identified subset of the end-to-end workflow is implemented.
Planned: the work describes a proposed or developing future capability.
See Current capabilities for the detailed matrix.