pages/examples/alignment.md

0001 @page examples_geometry_contexts Simulation and reconstruction geometry contexts
0002
0003 # Simulation and reconstruction geometry contexts
0004
0005 Alignment studies need simulation to place the detector modules differently from
0006 what reconstruction assumes. The Examples framework supports this directly: an
0007 `ActsExamples::AlgorithmContext` carries two geometry contexts, and one sequence
0008 can run both geometries at once.
0009
0010 There is no need to write measurements out of a simulation job and read them back
0011 into a separate reconstruction job. Measurement IO stores local parameters and a
0012 geometry identifier, so it carries no geometry context anyway - the two-context
0013 model expresses the same thing without the round trip.
0014
0015 ## The two contexts
0016
0017 | Member | Meaning |
0018 | --- | --- |
0019 | `recoGeoContext` | The geometry reconstruction assumes, i.e. the current alignment hypothesis. |
0020 | `simGeoContext` | The geometry the detector is actually built with, i.e. what simulation transports particles through. |
0021
0022 Both default to an empty context. A job that adds no context decorator behaves
0023 exactly as if there were a single context.
0024
0025 The rule for picking one is:
0026
0027 - A quantity derived from **simulation truth** - sim hits, truth particle
0028   positions on sensitive surfaces - uses `simGeoContext`. Simulation and
0029   digitization are entirely on this side.
0030 - A quantity derived from **reconstruction output** - track states, fitted
0031   parameters, space points, measurements as they are placed for pattern
0032   recognition - uses `recoGeoContext`. Seeding, track finding, fitting,
0033   extrapolation and vertexing are entirely on this side.
0034 - A chain that is neither, such as material mapping, standalone propagation or a
0035   geometry dump, uses `recoGeoContext`.
0036
0037 Performance writers legitimately use both. `ActsExamples::RootTrackStatesWriter`
0038 is the clearest case: its truth branch reads sim hits in `simGeoContext` while
0039 its measurement and track state branches sit in `recoGeoContext`, and the
0040 difference between them is the misalignment under study.
0041
0042 Writers that intersect a truth particle with a perigee or beamline surface are
0043 insensitive to the choice, because those surfaces carry no detector element and
0044 therefore no alignment payload.
0045
0046 ## Injecting a misalignment
0047
0048 `ActsExamples::AlignmentDecorator` decides which context(s) it writes through
0049 `Config::target`:
0050
0051 | Target | Effect |
0052 | --- | --- |
0053 | `eSim` | Only simulation sees the alignment, reconstruction stays nominal. |
0054 | `eReco` | Only reconstruction sees it, simulation stays on the design geometry. |
0055 | `eBoth` | Both, i.e. a detector that is misaligned but perfectly known. This is the default. |
0056
0057 Either single-sided target produces the sim/reco mismatch an alignment study
0058 needs. `eReco` is usually the more convenient one: simulation stays on the design
0059 geometry, so the truth sample is the same across all distortions and can be
0060 reused. Reach for `eSim` when the built geometry itself is what varies, for
0061 example a test beam telescope whose acceptance depends on where the modules
0062 really sit.
0063
0064 Chain two decorators to give simulation and reconstruction two *different*
0065 non-nominal alignments, which is what an alignment iteration looks like.
0066
0067 ## Caveats
0068
0069 - **Geant4 cannot be misaligned this way.** `ActsExamples::Geant4Simulation`
0070   forwards `simGeoContext` to the user actions, but the G4 geometry itself is
0071   built once and is not context aware, so per-event transforms never reach G4
0072   transport. Use Fatras.
0073 - **Navigation is built on the nominal geometry.** Layer arrays, volume
0074   boundaries and surface binning are constructed once, so misalignments have to
0075   stay small enough not to break navigation.
0076 - **A single-sided target degrades pattern recognition.** Seeding and track
0077   finding work in `recoGeoContext`, so a shift they do not know about costs
0078   efficiency before it ever reaches the fit.
0079
0080 ## Where to look
0081
0082 - `Examples/Scripts/Python/misaligned_simulation.py` - a telescope with one
0083   shifted layer, showing the residual bias that appears when only simulation
0084   sees the shift.
0085 - `Examples/Scripts/Python/millepede_alignment.py` - the same setup feeding a
0086   Millepede alignment that fits the shift back out.
0087 - `Python/Examples/tests/test_alignmentdecorator.py` - the corresponding tests.