clic/clusters/v1.6/README.md

# Model Card for mlpf-clic-clusters-v1.6

This model reconstructs particles in a detector, based on the tracks and calorimeter clusters recorded by the detector.

## Model Details

### Model Description

<!-- Provide a longer summary of what this model is. -->

- **Developed by:** Joosep Pata, Eric Wulff, Farouk Mokhtar, Mengke Zhang, David Southwick, Maria Girone, David Southwick, Javier Duarte
- **Model type:** graph neural network with learnable structure in locality-sensitive hashing bins
- **License:** Apache License

### Model Sources

<!-- Provide the basic links for the model. -->

- **Repository:** https://github.com/jpata/particleflow/releases/tag/v1.6
- **Paper:** https://doi.org/10.48550/arXiv.2309.06782

## Uses

<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->

### Direct Use

<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->

This model may be used to study the physics and computational performance on ML-based reconstruction in simulation.

### Out-of-Scope Use

<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->

This model is not intended for physics measurements on real data. 

## Bias, Risks, and Limitations

<!-- This section is meant to convey both technical and sociotechnical limitations. -->

The model has only been trained on simulation data and has not been validated against real data.

## How to Get Started with the Model

Use the code below to get started with the model.

```
git clone https://github.com/jpata/particleflow/releases/tag/v1.6
cd particleflow

#Download the software image
wget https://hep.kbfi.ee/~joosep/tf-2.14.0.simg

#Download the checkpoint
wget https://huggingface.co/jpata/particleflow/resolve/clic_clusters_v1.6/weights-96-5.346523.hdf5
wget https://huggingface.co/jpata/particleflow/resolve/clic_clusters_v1.6/opt-96-5.346523.pkl

#Launch a shell in the software image
apptainer shell --nv tf-2.14.0.simg

#Continue the training from a checkpoint
python3 mlpf/pipeline.py train --config parameters/clic.yaml --weights weights-96-5.346523.hdf5 --batch-multiplier 0.5

#Run the evaluation for a given training directory, loading the best weight file in the directory
python3 mlpf/pipeline.py evaluate --train-dir experiments/clic-REPLACEME
```

## Training Details

### Training Data

Trained on the following dataset:
Pata, J., Wulff, E., Duarte, J., Mokhtar, F., Zhang, M., Girone, M., & Southwick, D. (2023). Simulated datasets for detector and particle flow reconstruction: CLIC detector, machine learning format (v1.5.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.8409592

### Training Procedure 

```
python3 mlpf/pipeline.py train --config parameters/clic.yaml
```

## Evaluation

```
python3 mlpf/pipeline.py evaluate --train-dir experiments/clic-REPLACEME
```

## Citation

**BibTeX:**

```
@misc{pata2023scalable,
      title={Scalable neural network models and terascale datasets for particle-flow reconstruction}, 
      author={Joosep Pata and Eric Wulff and Farouk Mokhtar and David Southwick and Mengke Zhang and Maria Girone and Javier Duarte},
      year={2023},
      eprint={2309.06782},
      archivePrefix={arXiv},
      primaryClass={physics.data-an}
}
```
## Glossary

PF - particle flow reconstruction

## Model Card Contact

Joosep Pata, joosep.pata@cern.ch