pages/examples/material_mapping.md

0001 @page material_mapping_workflow Material mapping workflow (source of truth)
0002
0003 # Material mapping workflow (source of truth)
0004
0005 This page is the canonical reference for the ACTS Examples material mapping chain.
0006 It explains the end-to-end logic and points to the concrete scripts and tests that
0007 define current behavior.
0008
0009 ## Overview
0010
0011 Material mapping in the Examples pipeline is a three-step process:
0012
0013 1. **Record material in detailed simulation (Geant4)**
0014    Shoot particles through the detector's full simulation geometry and store
0015    material interactions per track.
0016
0017 2. **Map recorded material onto ACTS tracking surfaces**
0018    Collect surfaces configured to carry material (via `ProtoSurfaceMaterial` in
0019    geometry/material configuration), assign recorded interactions to these
0020    surfaces, and average into a compact material map.
0021
0022 3. **Validate mapped material**
0023    Propagate particles through the detector decorated with the produced map and
0024    record material tracks again for comparison against Geant4-based recording.
0025
0026 ## Scripts (ODD workflow)
0027
0028 The following scripts implement the three stages:
0029
0030 - Recording: `Examples/Scripts/Python/material_recording.py`
0031 - Mapping: `Examples/Scripts/Python/material_mapping.py`
0032 - Validation: `Examples/Scripts/Python/material_validation.py`
0033
0034 Example commands (Open Data Detector):
0035
0036 ```console
0037 python material_recording.py -n1000 -t1000 -o odd_material_geant4
0038 python material_mapping.py -n 1000000 -i odd_material_geant4 -o odd_material
0039 python material_validation.py -n 1000 -t 1000 -m odd_material_map.root -o odd_material_validated -p
0040 ```
0041
0042 > [!tip]
0043 > Run these from `Examples/Scripts/Python` or prefix each command with
0044 > `python Examples/Scripts/Python/<script>.py ...` from the repository root.
0045
0046 ## Step-by-step logic
0047
0048 ### 1) Material recording (`material_recording.py`)
0049
0050 - Uses Geant4 material recording to create per-track material information.
0051 - Produces a `<output>.root` ROOT file containing material tracks.
0052 - Typical output for the command above: `odd_material_geant4.root`.
0053
0054 ### 2) Material mapping (`material_mapping.py`)
0055
0056 - Reads recorded material tracks (`RootMaterialTrackReader`).
0057 - Collects mappable surfaces from tracking geometry
0058   (`trackingGeometry.extractMaterialSurfaces()`).
0059 - Builds assignment/accumulation components and performs averaging onto the
0060   selected surfaces.
0061 - Writes mapped outputs using the chosen output stem:
0062   - `<stem>_map.root` and/or `<stem>_map.json`
0063   - `<stem>_mapped.root`
0064   - `<stem>_unmapped.root`
0065
0066 ### 3) Material validation (`material_validation.py`)
0067
0068 - Decorates geometry from `--map`, then validates material response by producing
0069   material tracks from mapped material.
0070 - Writes `<output>.root` with collection `material_tracks` by default.
0071 - `-p` / `--propagate` enables an additional propagation/navigation-based
0072   collection, written as `<output>_propagated.root`, useful to expose potential
0073   navigation-related effects in material collection.
0074
0075 ## Comparison example
0076
0077 The figure below overlays Geant4, mapped, validated, and propagated profiles
0078 for `t_X0` vs `eta`, with a ratio panel.
0079
0080 ![Overlay and ratio for material profiles.](material/overlay_profile_ratio_v_eta_t_X0.png)
0081
0082 ## Tests that guard this workflow
0083
0084 Primary tests live in `Python/Examples/tests`:
0085
0086 - `Python/Examples/tests/conftest.py`
0087   - `material_recording_session` fixture generates reusable Geant4 material tracks.
0088 - `Python/Examples/tests/test_examples.py`
0089   - `test_material_recording`
0090   - `test_material_mapping`
0091 - `Python/Examples/tests/root_file_hashes.txt`
0092   - Reference hashes for workflow outputs.
0093
0094 These tests are the executable reference for expected output structure and
0095 regression tracking.