Rewrite the absorber fast simulation example

The previous text described the behaviour of the branch before the envelope
existed, so most of it was wrong rather than merely stale.

- run.sh now fixes the seed in both runs. Without it o2-sim picks one per run,
  the two simulations see different primaries, and the difference between them
  is mostly different events: an unseeded pair read 2.25x faster, a seeded pair
  reads 5%.
- Measured on five pp events with PIPE and ABSO: 1547 tracks per event with
  detailed transport against 1144 with the toy model, 14.9 s against 14.2 s.
- Says why a quarter fewer tracks buys five percent of wall clock, and that
  neither number is a performance result or a physics validation.
- Records the two properties that surprise a reader of the output: a fast step
  does not call the sensitive detector, and its secondaries carry kPNull.

Author: sawenzel

run/SimExamples/FastSim_Absorber/README.md

@@ -4,7 +4,8 @@ Replaces the detailed transport through the ALICE front absorber by a model, and
 compares the result against a full simulation of the same events.
 
 `run.sh` runs both: a reference `o2-sim` with PIPE and ABSO only, and the same
-setup with the fast simulation switched on.
+setup with the fast simulation switched on. Both use the same seed, so the two
+simulations see the same primaries and the comparison is paired.
 
 | file | |
 |---|---|
@@ -16,102 +17,90 @@ setup with the fast simulation switched on.
 The feature does nothing unless a model is named:
 
 ```
---configKeyValues "G4.fastSimModels=toyAbsorber;G4.fastSimRegions=ABSO_AIR_ENVELOPE"
+--configKeyValues "G4.fastSimModels=toyAbsorber;G4.fastSimEnvelope=AFaM"
 ```
 
-`G4.fastSimMinEnergy` (GeV, default 1) is the threshold below which the detailed
-transport still runs, because a surrogate below it would be extrapolating and
-the transport there is cheap anyway.
+`G4.fastSimEnvelope` is the volume the model stands in for — here `AFaM`, the
+mother of the whole absorber. `G4.fastSimMinEnergy` (GeV, default 1) is the
+threshold below which the detailed transport still runs.
 
 ## What the model does
 
-`toyAbsorber` is a placeholder. It returns the incident particle continuing in
-its direction with the energy attenuated exponentially over the path through the
-envelope — a real absorber turns one incident hadron into a shower, so the
-numbers this produces are not physics. It is here so that the machinery can be
-exercised end to end before a trained model exists.
+`toyAbsorber` is a placeholder: it returns the incident particle continuing in
+its direction with the energy attenuated exponentially over its path through the
+envelope. A real absorber turns one incident hadron into a shower, so these are
+not physics numbers.
 
 A model implements one function, `sample()`, which maps the particle that
 entered the region to the particles that leave it
-(`Detectors/FastSim/include/FastSim/FastSimModel.h`). Everything around it —
+(`Detectors/FastSim/include/FastSim/FastSimModel.h`). The surrounding work —
 measuring the distance to the envelope surface, killing the incident particle,
-stacking what comes back, booking the energy difference as a deposit — is shared
-and does not have to be reimplemented.
+stacking what comes back, booking the energy difference as a deposit — is shared.
 
-## Why the region is named `ABSO_AIR_ENVELOPE`
+## How the envelope and the regions relate
 
-Regions are selected by tracking medium, which Geant4-VMC maps to that medium's
-material, adding every volume of that material to the region. A volume can
-therefore only be addressed on its own if its material is its own, which is why
-`AFaM` — the mother volume of the whole absorber — carries a dedicated air
-material (`Detectors/Passive/src/Absorber.cxx`). Selecting it means "the
-absorber", with all of its daughters inside.
+Geant4 consults a fast simulation model through *regions*, and in O2 a region can
+only ever be "every volume of a given material": the VMC special cuts make every
+logical volume a root of its own material's region, and Geant4 stops propagating
+a region at any such daughter. A region named after `AFaM` would therefore
+contain `AFaM` alone, which tracks skip entirely because its daughters touch its
+surface.
 
-Selection by volume is not available: the VMC special cuts already root every
-logical volume in a per-material region, and Geant4 allows a logical volume in
-exactly one region.
-
-## Status: the model does not fire on the muon-arm path
-
-Measured on a real run, and it is a limitation of the region mechanism rather
-than of the model.
-
-`ABSO_AIR_ENVELOPE` selects a region containing `AFaM` **and nothing else**. The
-VMC special cuts create one `G4Region` per material and make every logical volume
-a root of its own, and Geant4 stops propagating a region down the tree at any
-daughter that is itself a region root — so `AFaMgRing` is in `ABSO_MAGNESIUM$`,
-`AFaGraphiteConeO` in `ABSO_CARBON0$`, and the absorber's mother region covers
-none of them. On top of that, `AFaM`'s daughters touch its surface, so a track
-entering the absorber lands straight in a daughter and never has `AFaM` as its
-volume at all.
-
-A 20 GeV muon fired into the muon-arm acceptance with `/tracking/verbose 1`
-therefore steps through the absorber identically with and without the fast
-simulation enabled:
+So the two jobs are separated. The regions are derived by walking the envelope's
+subtree and collecting its media, which for `AFaM` finds fourteen:
 
 ```
-   13     54.2   -0.238     -900  1.99e+04   0.0405      287       902   AFaMgRing Transportation
-   14     55.5   -0.244     -920  1.99e+04     5.33       20       922 AFaGraphiteConeO Transportation
-   15     56.7   -0.254     -940  1.99e+04     5.33     20.2       942 AFaGraphiteConeO muIoni
+fast simulation: model toyAbsorber covers 14 media found under 'AFaM'
+Adding fast simulation model toyAbsorber to regions ABSO_AIR0$ ABSO_AIR_ENVELOPE0$
+  ABSO_CONCRETE2$ ABSO_POLYETHYLEN2$ ABSO_CARBON0$ ABSO_CARBON2$ ABSO_MAGNESIUM$
+  ABSO_Ni-W-Cu0$ ABSO_Ni-W-Cu2$ ABSO_LEAD0$ ABSO_LEAD2$ ABSO_STAINLESS STEEL0$
+  ABSO_STAINLESS STEEL2$
 ```
 
-Only `muIoni`, `eIoni`, `Transportation` and `specialCutForElectron` appear; no
-fast-simulation process does.
-
-So a region in O2 can be "every volume of a given material" but not "this volume
-and its daughters", and a surrogate for a whole module is not expressible through
-this interface as it stands. The two ways forward are to name the absorber's
-constituent materials and accept a per-piece envelope, or to change
-`TG4RegionsManager` upstream so that the cuts regions do not claim every volume
-as a root.
-
-**Do not read the track counts below as a measurement of the model.** They come
-from two runs whose random sequences diverge before the absorber is even reached
-— visible in the beam pipe — so the difference is not attributable to the fast
-simulation.
+What the model measures against is the envelope itself, read from the track's own
+touchable. `ModelTrigger` also requires geometric containment in it, which is
+what excludes the steel support cradle — it shares its material with the end
+plate, so no selection by material could separate them.
 
 ## Measured
 
-Five pp minimum-bias events, Pythia8 and Geant4, `-m PIPE ABSO`, on one EPN node
-against `O2PDPSuite/daily-20260819-0000-1`:
+Five pp minimum-bias events, Pythia8 and Geant4, `-m PIPE ABSO`, same seed, one
+EPN node against `O2PDPSuite/daily-20260819-0000-1`:
 
 | | full | fast |
 |---|---|---|
-| tracks per event | 3544 | 3160 |
-| transport real time | 29.8 s | 28.0 s |
+| tracks per event | 1547 | 1144 |
+| transport real time | 14.9 s | 14.2 s |
 
-geant4_vmc does report that the region resolved, which is necessary but, as
-above, not sufficient:
+A 20 GeV muon fired into the muon-arm acceptance with `/tracking/verbose 1`
+shows what the model does to a single track:
 
 ```
-fast simulation is ENABLED for regions 'ABSO_AIR_ENVELOPE'
-fast simulation: registering model toyAbsorber above 1 GeV
-Adding fast simulation model toyAbsorber to regions ABSO_AIR_ENVELOPE0$
+   10     54.4   -0.137     -900  1.99e+04   0.0749      287       902   AFaMgRing Transportation
+   11     54.4   -0.137     -900         0 1.99e+04  4.1e+03     5e+03   AFaMgRing G4FastSimulationManagerProcess
 ```
 
-where the last line is the tracking medium having resolved to its material, which
-is the step that silently does nothing if the medium name is wrong.
-
-**These numbers are not a performance result and not a measurement of the
-model** — see the section above. They are recorded only to show what the example
-currently produces.
+One step of 4.1 m across the whole absorber, in place of roughly twenty `muIoni`
+steps through graphite, concrete and steel.
+
+## What these numbers are not
+
+**Not a performance result.** A quarter fewer tracks buys only five percent of
+wall clock, because the tracks the absorber's shower contributes are cheap
+low-energy ones and most of the CPU in this setup is spent elsewhere. And with
+minimum-bias pp only the forward cone reaches the absorber at all. A CPU number
+worth quoting needs a workload where the absorber is on the critical path — a
+forward-biased generator, or the full detector where the muon arm is the point.
+
+**Not a physics validation.** The toy returns one particle where a real absorber
+returns a shower, so the track counts above say more about the placeholder than
+about the absorber. Comparing the outgoing multiplicity and spectrum against a
+full simulation is what a trained model has to pass, and that is the measurement
+this example is scaffolding for.
+
+Two further caveats worth knowing when reading any output of this: a fast step
+does not call the sensitive detector, so its steps disappear from MCStepLogger
+(harmless for a passive envelope, which has no hits); and secondaries the model
+creates carry `TMCProcess` `kPNull`, the code geant4_vmc gives to everything it
+has no VMC equivalent for, so they cannot be told apart from other tracks by
+process alone.

run/SimExamples/FastSim_Absorber/run.sh

@@ -22,22 +22,26 @@ set -x
 EVENTS=5
 MODULES="-m PIPE ABSO"
 GEN="-g pythia8pp"
+# The same seed in both runs, so the two simulations see the SAME primaries and
+# the comparison is paired. Without it o2-sim picks a seed per run and the
+# difference between the two is mostly different events.
+SEED="--seed 12345"
 # Alignment is irrelevant here and switching it off keeps the example from
 # needing a CCDB connection and an alien token.
 COMMON="align-geom.mDetectors=none"
 
 # --------------------------------------------------------------- 1. reference
 # Detailed transport, for comparison.
 mkdir -p full && cd full
-o2-sim-serial -n ${EVENTS} ${GEN} -e TGeant4 ${MODULES} -o full \
+o2-sim-serial -n ${EVENTS} ${GEN} ${SEED} -e TGeant4 ${MODULES} -o full \
     --configKeyValues "${COMMON}" > logfull 2>&1
 cd ..
 
 # -------------------------------------------------------------------- 2. fast
 # G4.fastSimModels is what switches the feature on; with it empty (the default)
 # nothing about the simulation changes.
 mkdir -p fast && cd fast
-o2-sim-serial -n ${EVENTS} ${GEN} -e TGeant4 ${MODULES} -o fast \
+o2-sim-serial -n ${EVENTS} ${GEN} ${SEED} -e TGeant4 ${MODULES} -o fast \
     --configKeyValues "${COMMON};\
 G4.fastSimModels=toyAbsorber;\
 G4.fastSimEnvelope=AFaM;\