Warning, /snippets/Tracking/particle2hit/README.md is written in an unsupported language. File is not indexed.
0001 # MC particles to tracking hits
0002
0003 Shujie Li with ChatGPT, 10.2026
0004
0005 Read an EDM4hep simulation ROOT file into linked pandas tables of MC particles
0006 and their directly associated **simulated tracking hits**. The reader discovers
0007 tracker-hit collections and CellID layouts from the file; ROOT, PODIO and DD4hep
0008 Python bindings are not required.
0009
0010 * This script is designed for tracker acceptance study. A similar script to extract
0011 Reconstructed hits on each surface and group by source particles are available
0012 at `snippets/Tracking/svt_rate_per_source`.
0013
0014 ## Getting started
0015
0016 Requires Python 3.9+, NumPy, Awkward Array, Uproot and pandas. The notebook also
0017 uses Matplotlib and IPython/Jupyter. Tested in the EIC 26.08 environment.
0018
0019 Open [mc_tracking_hits_example.ipynb](mc_tracking_hits_example.ipynb) from this
0020 directory, set `ROOT_FILE` and the MC cuts in section 1, and run all cells with
0021 a kernel containing these dependencies. The notebook demonstrates layer
0022 selection, complete hit attributes, per-particle hit counts and diagnostic plots.
0023
0024 ## Python usage
0025
0026 ```python
0027 from mc_tracking_hits import read_mc_tracking_hits
0028
0029 tables = read_mc_tracking_hits(
0030 "simulation.root", pdgs=[211, -211],
0031 eta_range=(0.9, 1.0), p_range=(4.5, 5.5), stop=2000,
0032 )
0033 particles, hits = tables["particles"], tables["hits"]
0034
0035 # VertexBarrel L0 in the example geometry; verify IDs for your geometry.
0036 l0_hits = hits.loc[
0037 (hits.hit_collection == "VertexBarrelHits")
0038 & (hits.system == 31) & (hits.layer == 0)
0039 ]
0040 ```
0041
0042 | Result | Contents |
0043 | --- | --- |
0044 | `particles` | Selected MC particles, including zero-hit particles, with kinematics and total hit counts |
0045 | `hits` | Associated hits with all stored scalar attributes, original references, exact uint64 CellIDs and decoded fields |
0046 | `surfaces` | Observed collection/system/layer groups with hit and distinct-particle counts |
0047 | `metadata` | Source identity, selections, collection IDs, CellID layouts and units |
0048
0049 Join particles and hits on `file_id`, `event_entry`, `mc_index`. Select a layer
0050 by **collection, system and layer**, since layer numbers are reused across
0051 detectors. These groups are detector layers, not individual ACTS surfaces;
0052 decoded module/sensor fields retain finer segmentation. Missing encoded fields
0053 are represented by NA. Positions/path lengths are mm, momentum/energy GeV,
0054 time ns and angles radians; decoded CellID fields are integer identifiers.
0055
0056 By default, `primary_only=True` selects `generatorStatus == 1`; multiple MC
0057 particles per event are supported. Set it to `False` to include other stored MC
0058 particles. Eta and momentum cuts use MC kinematics and half-open `[low, high)`
0059 ranges. Only direct hit-to-particle links are followed, without secondary
0060 ancestry. Hit presence does not imply track reconstruction or a geometric
0061 intersection test.
0062
0063 ## Large files
0064
0065 `read_mc_tracking_hits()` collects one file/prefix in memory. For batch analysis,
0066 reduce each block instead of retaining all raw hit tables:
0067
0068 ```python
0069 from mc_tracking_hits import iter_mc_tracking_hits
0070
0071 for tables in iter_mc_tracking_hits("simulation.root", pdgs=[211], step_size=5000):
0072 hits = tables["hits"]
0073 # Select layers and accumulate counts or histograms here.
0074 ```
0075
0076 Use `collections=[...]` to restrict I/O. If the file lacks CellID-layout metadata,
0077 pass `encodings` from the matching geometry; `load_readout_encodings(xml_files)`
0078 reads readout descriptions from explicit detector XML files without expanding
0079 includes. Input ROOT files are opened read-only.
