Warning, /snippets/Tracking/BackgroundStudy/README_extract_generator_hepmc.md is written in an unsupported language. File is not indexed.
0001 # Recover generator particles from npsim output
0002 Shujie Li with Chatgpt, 10.2026
0003
0004 [`extract_generator_hepmc.py`](extract_generator_hepmc.py) converts the generator
0005 record saved in MCparticles either from EDM4hep or EDM4eic file into HepMC3 ASCII, suitable for use
0006 as input to another npsim run. It is a standalone script: no local imports,
0007 PODIO Python bindings, or detector geometry are needed.
0008
0009 ## Requirements and use
0010
0011 Python 3 with `numpy`, `awkward`, `uproot`, and `pyhepmc`:
0012
0013 ```bash
0014 python -m pip install numpy awkward uproot pyhepmc
0015 python extract_generator_hepmc.py sample.edm4hep.root source.hepmc3 --max-events 2
0016 ```
0017
0018 Validated with `pyhepmc 2.14.0` and `uproot 5.5.1`.
0019
0020 Omit `--max-events` to process every event. The output directory must already
0021 exist. Existing output files are never overwritten. During conversion the
0022 script writes `source.hepmc3.partial`, then renames it on success. If conversion
0023 fails, the partial file stays available for inspection; choose a new output
0024 name or move it aside before retrying.
0025
0026 ## What is preserved
0027
0028 - Keep MCParticles with **simulatorStatus bit 30 clear**
0029 (`BITCreatedInSimulation`); discard particles created by detector simulation.
0030 This keeps all saved generator statuses, including incoming and intermediate
0031 particles.
0032 - Preserve particle order, PDG IDs, generator statuses, masses, event numbers,
0033 and parent/daughter connections within the retained record.
0034 - Recompute energy as `E = sqrt(px² + py² + pz² + m²)`. Momentum, energy, and
0035 mass use GeV; positions use mm. Convert EDM4hep time in ns to HepMC `ct` in
0036 mm using `ct = 299.792458 × time`.
0037
0038 The input must contain the standard `events` tree, `EventHeader`, `MCParticles`,
0039 and its parent/daughter relation branches (listed in `BRANCHES` in the script).
0040 Each relation index is interpreted within that event's `MCParticles` collection.
0041 Events are read individually with the array cache disabled, so memory depends
0042 on event size rather than the number of events in the file.
0043
0044 ## Reconstruction limits
0045
0046 This reconstructs the saved particle record, not the original HepMC file byte
0047 for byte. Generator weights, run metadata, and unsaved attributes are not
0048 recovered. Children with the same parent set share a vertex at the parents'
0049 common endpoint; the nearest child's stored production position supplies the
0050 time. Parentless particles must start at `(x, y, z, ct) = (0, 0, 0, 0)`.
0051 Inconsistent relations, incompatible parent endpoints, and unsupported source
0052 positions raise errors rather than silently changing the record.
