Update README.md

README.md

@@ -11,190 +11,117 @@ datasets:
 - Avencast/EveNet-ExoticHiggs-H2a4b
 - Avencast/EveNet-TT2L-QuantumCorrelation
 ---
-# Model Card for Model ID
 
-<!-- Provide a quick summary of what the model is/does. -->
+# Model Card for EveNet
 
-This modelcard aims to be a base template for new models. It has been generated using [this raw template](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md?plain=1).
+EveNet is an event‑level foundation model for collider physics. It represents each collision event as a combination of a fixed‑length point cloud of reconstructed objects and a vector of global observables, and processes these inputs with a hybrid point–edge transformer (PET) backbone. The backbone encodes both local geometric relationships and global context and feeds several task‑specific heads that support classification, regression, combinatorial assignment, segmentation, and generative modelling. EveNet is pretrained on large‑scale Standard Model (SM) simulations using a hybrid of supervised and self‑supervised objectives and can be fine‑tuned for a broad range of downstream analyses.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
+EveNet treats a hadron‑collider event as a **point‑cloud** of up to 18 reconstructed objects (jets, electrons, muons, etc.) with seven features each (energy, transverse momentum (p_{\mathrm{T}}), pseudorapidity (\eta), azimuthal angle (\phi), b‑tag score, lepton flag and charge) plus optional per‑event scalars. Masks indicate which padded entries are valid. A separate normalisation layer handles global variables. The backbone consists of three stages:
 
+1. **Global embedding:** a learned embedding of global scalars configured via `Body.GlobalEmbedding`.
+2. **PET body:** a point–edge transformer with attention layers and k‑nearest‑neighbour edges, configurable by depth, number of heads and feature‑drop rate. A 10 % feature dropout was applied during pretraining to encourage robustness.
+3. **Object encoder:** mixes the particle and global tokens, again using configurable attention layers.
 
+Multiple **task‑specific heads** are attached to this shared representation. Discriminative heads include classification, regression, assignment (resonance matching) and segmentation. Generative heads implement diffusion‑based self‑supervised reconstruction of visible objects and supervised generation of invisible particles (such as neutrinos). Conditioning on the diffusion time unifies discriminative and generative tasks within a single latent space.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+* **Developed by:** EveNet collaboration (Ting‑Hsiang Hsu, Bai‑Hong Zhou, Qibin Liu, Yue Xu, Shu Li, Wei‑Shu Hou, Benjamin Nachman, Shih‑Chieh Hsu, Vinicius Mikuni, Yuan‑Tang Chou, Yulei Zhang et al.).
+* **License:** MIT.
+* **Model type:** Hybrid point–edge transformer with diffusion‑based generative heads and discriminative heads.
+* **Languages:** Not language‑based – inputs are numeric features of physics objects.
+* **Fine‑tuned from:** Pretrained from scratch on SM simulations; this is the base foundation model.
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+* **Repository:** [GitHub – EveNet‑Full](https://github.com/EveNet-HEP/EveNet-Full)
+* **Documentation:** [EveNet Documentation Portal](https://evenet-hep.github.io/EveNet-Full/)
+* **Paper:** [“EveNet: A Foundation Model for Particle Collision Data Analysis”](https://huggingface.co/papers/2601.17126).
+* **Pretrained Weights:** Available on [Hugging Face](https://huggingface.co/Avencast/EveNet).
 
 ## 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. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
+### Intended Uses
 
-### Out-of-Scope Use
+EveNet is designed as a **multi‑task foundation model** for collider‑physics analyses. It supports event‑level classification, combinatorial reconstruction, segmentation of final‑state particles and generative modeling for missing or masked objects. Intended uses include:
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+* **Pretraining and fine‑tuning:** Use the released checkpoints as a starting point for new analyses. The pretraining corpus consists of approximately 500 million proton–proton collision events at (\sqrt{s}=13,\text{TeV}) spanning QCD multijet, top‑quark, (W/Z)+jets and diboson processes. Events were simulated with **MADGRAPH5_aMC@NLO** for matrix elements, **PYTHIA** for parton showering and hadronisation, and **Delphes** for fast detector simulation. Hard objects were required to satisfy (p_{\mathrm{T}}>10,\text{GeV}) (20 GeV for jets) and central pseudorapidity |(\eta)|<2.5, and additional preselections ensured at least two jets for QCD events and appropriate multiplicities for other processes.
+* **Downstream analyses:** The pretrained model can be fine‑tuned on smaller datasets for tasks such as heavy‑resonance searches, exotic Higgs decays ((H\to aa\to 4b)), quantum‑correlation measurements in (t\bar{t}) dilepton events and anomaly detection on collision data. Example datasets and configurations for these tasks are provided in the EveNet benchmark repositories.
 
-[More Information Needed]
+### Out‑of‑Scope Uses
 
-## Bias, Risks, and Limitations
+* **Non‑HEP data:** EveNet is tailored to collider physics; it is not a general machine‑learning model for images, language or tabular data outside particle‑collision analyses.
+* **Human or personal data:** The model should not be applied to sensitive personal data. It is trained exclusively on simulated physics events and does not generalize to human‑related tasks.
+* **Uncalibrated inference on real data:** While EveNet transfers well to collision data, users must validate model performance and calibrate outputs to ensure physical fidelity, particularly when applying the generative heads to unseen detectors or energy regimes.
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+## Bias, Risks & Limitations
 
-[More Information Needed]
+* **Simulation bias:** The pretraining dataset comprises simulated SM processes that include generator‑level cuts (minimum (p_{\mathrm{T}}), multiplicity requirements, etc.). These cuts bias the population toward energetic events; analyses of soft‑physics regimes or rare final states may require additional training data.
+* **Model scope:** The model inputs are limited to reconstructed objects with seven features each. Analyses requiring detailed detector information (e.g., calorimeter cells) or more than 18 objects may need to modify the architecture or use custom preprocessing.
+* **Generalisation to non‑SM physics:** Although EveNet demonstrates transfer to unseen processes, it has been pretrained on SM simulations. Performance on exotic signatures not represented in the pretraining corpus may be limited.
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+Users should:
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
+* Provide **domain‑appropriate training data** for any new physics regime and re‑estimate normalisation statistics when modifying the input schema.
+* Validate the model on **collision data** and apply calibration procedures when using generative outputs to enforce physical constraints.
+* Be aware of **class imbalances** and provide appropriate per‑event weights to the classification head when training.
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
+The foundation model was trained on a corpus of roughly **3 billion** simulated SM events, from which **about 500 million** were retained after preselections. These simulations were generated with **MADGRAPH5_aMC@NLO** for hard processes, **PYTHIA** for parton showers and hadronisation, and **Delphes** for fast detector simulation. Cuts of (p_{\mathrm{T}}>10,\text{GeV}) for leptons and (p_{\mathrm{T}}>20,\text{GeV}) for jets and |(\eta)|<2.5 were imposed. For QCD events at least two jets were required.
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
+EveNet uses **PyTorch Lightning** with a **Ray**‑based distributed training pipeline. Pretraining combines:
 
+* **Supervised objectives**: event‑level classification of physics processes, object assignment to resonances and segmentation of final‑state particles. Regression targets (momentum, masses) are normalised using mean and standard‑deviation tensors.
+* **Self‑supervised and supervised generative objectives**: diffusion models reconstruct visible inputs and predict invisible neutrinos; both tasks are conditioned on a diffusion time (t) to unify generative and discriminative regimes.
 
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+An **Exponential Moving Average (EMA)** of the weights is maintained during training; training scripts allow resuming from checkpoints and replacing model weights with EMA weights before saving. The default configuration uses feature dropout to encourage generalisation. For fine‑tuning, the backbone learning rate may be reduced relative to task‑specific heads, and pretraining weights can be loaded safely with mismatched layers skipped.
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
+The EveNet paper evaluates the pretrained model on four downstream tasks:
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+1. **Heavy resonance search:** fine‑tuning on simulated searches for a heavy resonance decaying to a light scalar and the SM Higgs. EveNet shows improved sensitivity compared with scratch and self‑supervised baselines.
+2. **Exotic Higgs decays ((H\to aa\to 4b))**: improved performance relative to dedicated models.
+3. **Quantum correlations in (t\bar{t}) dilepton events:** EveNet pretrained on 500 million events achieved a normalised uncertainty (\Delta D) of **1.61 %** on the entanglement‑sensitive observable after fine‑tuning with 15 % of typical training statistics, outperforming scratch and self‑supervised baselines. It also reached **82 % pairing accuracy**, several points above scratch (80 %) and SSL (79 %) models.
+4. **Anomaly detection on CMS Open Data:** Generative diffusion heads were fine‑tuned on 2016 dimuon data to rediscover the Υ meson. EveNet replaced the conditional normalising flow baseline with a generative model that directly produces dimuon point clouds; after calibration, it achieved competitive or superior anomaly significance while maintaining physical fidelity.
 
-[More Information Needed]
+## How to Get Started
 
-### Results
+Install the package via pip:
 
-[More Information Needed]
+```bash
+pip install evenet
 
-#### Summary
+# convert .npz files to parquet and prepare normalization
+python preprocessing/preprocess.py --config share/event_info/pretrain.yaml --file /path/to/mydata.npz --store_dir /path/to/output
 
+# fine‑tune the model
+evenet-train my_finetuning_config.yaml
+```
 
+Pretrained weights can be loaded by specifying `pretrain_model_load_path` in the YAML configuration. For a detailed description of configuration options, consult the documentation site.
 
-## Model Examination [optional]
+## Citation
 
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## 📄 Citation
-
-If you use this model, please cite:
+If you use this model in your research, please cite:
 
 ```bibtex
-@article{zhang2026evenet,
-  title={EveNet: A Foundation Model for Particle Collision Data Analysis},
-  author={Zhang, Yulei and others},
-  journal={arXiv preprint arXiv:2601.17126},
-  year={2026}
+@article{Hsu:2026sww,
+  author        = {Ting-Hsiang Hsu and others},
+  title         = {{EveNet: A Foundation Model for Particle Collision Data Analysis}},
+  eprint        = {2601.17126},
+  archivePrefix = {arXiv},
+  primaryClass  = {hep-ex},
+  month         = {1},
+  year          = {2026}
 }
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+```