MaskPflow
Particle flow as masked token generation. From an event's topoclusters and tracks, MaskPflow generates its truth particles as VQ-VAE tokens with MaskedGIT (parallel, iterative unmasking); the truthpart VQ-VAE of HEP4M decodes them to pT, ฮท, ฯ, E and class.
A 17.2M-parameter bidirectional transformer (d_model 384, 8 layers, head dim 64), trained in fp32 on the 40M-event COCOA single-jet train split (tokenized with the HEP4M tokenizers).
| Folder | Version | Training | Decoding |
|---|---|---|---|
v2/ |
v2 (current) | count pass + NULL-dropped decoding pass, uniform mask ratio; 288M events (8 epochs incl. cooldown) | count first, NULL slots dropped, T = 16, linear schedule, argmax |
v1/ |
v1 | standard MaskedGIT, cosine mask ratio; 192M events | every slot decoded, NULL slots empty, T = 16, linear schedule, argmax |
Each folder holds model.safetensors (the weights) and config.json (architecture, training settings and
progress: steps, events seen, training time).
Use
The code is the maskpflow package, in the maskpflow/ folder of
FM-for-HEP/HEP4M (private). It also needs the HEP4M truthpart VQ-VAE
(vqxtrpartx128x8x1xxx3hty86rc6e3c) to turn tokens into particles; it is not part of this repository.
hf auth login # this repository is private: an account with access
hf download feltelwany/maskpflow --local-dir maskpflow_ckpts
from maskpflow.checkpoint import load_checkpoint
model, config = load_checkpoint("maskpflow_ckpts/v2") # model in eval mode, its config
Predictions for a list of events (SciMo-Bench prediction format, Parquet):
python scripts/predict.py --ckpt maskpflow_ckpts/v2 --config configs/v2.yaml \
--data_dir $HEP4M_DATA/Tokenized/val --vqvae_dir $HEP4M_DATA/Checkpoints/vqxtrpartx128x8x1xxx3hty86rc6e3c \
--events events.txt --out maskpflow_v2.parquet
In SciMo-Bench: bench/maskpflow_models.py with MASKPFLOW_CKPTS=maskpflow_ckpts.
Results
SciMo-Bench, 20k pflow validation events, cutflow=preselection, MI300A, fp32:
| E response IQR | E response median | N_reco โ N_truth | latency p50 (batch 1) | |
|---|---|---|---|---|
| v2 | 0.0777 | 0.995 | โ0.20 ยฑ 1.30 | 42.3 ms |
| v1 (NULL count) | 0.0853 | 0.983 | โ1.09 ยฑ 1.53 | 38.5 ms |