Address review: let a model override DoIt, and fix the example's config

- DoIt is Geant4's own entry point and is no longer final, so a model that does
  not fit the common shape can replace it rather than work around it.
- Its comment now says what it is: it wraps the logic common to every model and
  delegates the physics to sample().
- The example passed G4.fastSimRegions=ABSO_AIR_ENVELOPE, which overrides the
  envelope walk with a region containing only AFaM and reproduces exactly the
  behaviour this branch fixes. It now passes G4.fastSimEnvelope=AFaM.
- Drops an unreachable guard in the toy model: ModelTrigger only calls it above
  its threshold and an exponential of a finite path cannot reach zero.
- Comment wording throughout: say what a class is rather than what O2 used to
  lack, and "encloses" rather than "measures against".

Author: sawenzel

Detectors/FastSim/include/FastSim/FastSimModel.h

@@ -16,8 +16,10 @@
 ///
 /// A fast simulation model replaces the detailed transport through a region of
 /// the geometry by a function from the particle that enters it to the particles
-/// that leave it. `DoIt()` below is the plumbing and is the same for every
-/// model; a model implements `sample()` and nothing else.
+/// that leave it. `DoIt()` is Geant4's own entry point
+/// (`G4VFastSimulationModel::DoIt`); the implementation here wraps the logic
+/// common to every model and delegates the physics to `sample()`. A model that
+/// needs a different shape can still override `DoIt()`.
 
 #include "G4VFastSimulationModel.hh"
 
@@ -58,8 +60,8 @@ constexpr double kSurfaceEpsilonCm = 1e-5;
 /// Base class for fast simulation models.
 ///
 /// The model is attached to regions (see G4FastSimulation.h) purely so that
-/// Geant4 consults it; what it measures against is the ENVELOPE VOLUME named
-/// below, which is normally the mother volume of a whole module. The two are
+/// Geant4 consults it; what it encloses is the ENVELOPE VOLUME named below,
+/// which is normally the mother volume of a whole module. The two are
 /// deliberately separate, because a Geant4 region in O2 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
@@ -76,10 +78,12 @@ class FastSimModel : public G4VFastSimulationModel
   G4bool IsApplicable(const G4ParticleDefinition& particle) override;
   G4bool ModelTrigger(const G4FastTrack& fastTrack) override;
 
-  /// Measures the distance to the envelope surface, asks `sample()` what comes
-  /// out, kills the incident particle, stacks the result and books the energy
-  /// difference as a deposit.
-  void DoIt(const G4FastTrack& fastTrack, G4FastStep& fastStep) final;
+  /// Wraps the common logic of a fast simulation action and delegates the
+  /// physics to `sample()`: it measures the distance to the envelope surface,
+  /// kills the incident particle, stacks what `sample()` returned and books the
+  /// energy difference as a deposit. Override it for a model that does not fit
+  /// that shape.
+  void DoIt(const G4FastTrack& fastTrack, G4FastStep& fastStep) override;
 
  protected:
   /// Given the particle that entered, return everything that leaves. This is
@@ -91,7 +95,7 @@ class FastSimModel : public G4VFastSimulationModel
   /// the track is not inside it at all.
   int envelopeDepth(const G4Track* track) const;
 
-  G4String mEnvelope;     ///< logical volume the model measures against
+  G4String mEnvelope;     ///< logical volume the model encloses
   double mMinEnergy = 0.; ///< internal Geant4 units; below this the detailed transport runs
   mutable bool mWarned = false;
 };

Detectors/FastSim/include/FastSim/G4FastSimulation.h

@@ -53,8 +53,8 @@ class G4FastSimulation : public TG4VUserFastSimulation
   double mMinEnergy = 1.;
 };
 
-/// The one hook O2 was missing. Returns nullptr when no model is configured,
-/// which is exactly the behaviour before this file existed.
+/// Supplies Geant4-VMC with the fast simulation models and their regions.
+/// Returns nullptr when no model is configured, so nothing is set up.
 class G4RunConfiguration : public TG4RunConfiguration
 {
  public:

Detectors/FastSim/include/FastSim/ToyAbsorberFastSim.h

@@ -17,9 +17,9 @@
 namespace o2::fastsim
 {
 
-/// A toy model: one particle out, continuing along the incident direction with
-/// the energy exponentially attenuated over the path through the envelope.
-/// It exists to exercise the machinery, not to describe an absorber.
+/// A toy fast simulation model for the absorber: one particle out, continuing
+/// along the incident direction with the energy exponentially attenuated over
+/// the path through the envelope.
 class ToyAbsorberFastSim : public FastSimModel
 {
  public:

Detectors/FastSim/src/FastSimModel.cxx

@@ -120,8 +120,8 @@ void FastSimModel::DoIt(const G4FastTrack& fastTrack, G4FastStep& fastStep)
   input.mass = track->GetDefinition()->GetPDGMass() / CLHEP::GeV;
   input.time = track->GetGlobalTime() / CLHEP::ns;
   // Deliberately NOT GetEnvelopeSolid(): that is the region's root volume, i.e.
-  // one absorber piece. Measure against the envelope volume instead, using the
-  // transform the touchable already holds for that level.
+  // one absorber piece. Use the envelope volume instead, with the transform the
+  // touchable already holds for that level.
   const G4int level = envelopeDepth(track);
   const G4VTouchable* touchable = track->GetTouchable();
   const G4AffineTransform& toLocal =

Detectors/FastSim/src/ToyAbsorberFastSim.cxx

@@ -28,10 +28,9 @@ std::vector<FastSimOutput> ToyAbsorberFastSim::sample(const FastSimInput& input)
   // A toy transformation, not a physics model: the incident particle carries on
   // in its direction with the energy attenuated over the path through the
   // envelope. A trained model returns a shower here instead.
+  // Always positive: ModelTrigger only calls a model above its threshold, and
+  // an exponential of a finite path cannot reach zero.
   const double kinetic = input.kineticEnergy * std::exp(-input.exitDistance / kAbsorptionLengthCm);
-  if (kinetic <= 0.) {
-    return {};
-  }
   const double momentum = std::sqrt(kinetic * (kinetic + 2. * input.mass));
 
   FastSimOutput out;

run/SimExamples/FastSim_Absorber/run.sh

@@ -9,11 +9,10 @@
 # exponentially attenuated energy. What the example demonstrates is the
 # machinery, not the physics.
 #
-# The region is named by TRACKING MEDIUM. `ABSO_AIR_ENVELOPE` is the medium of
-# AFaM, the mother volume of the whole absorber, and it exists for exactly this
-# purpose: Geant4-VMC builds a region per MATERIAL and adds every volume of that
-# material to it, so a volume can only be addressed on its own if its material
-# is its own.
+# `G4.fastSimEnvelope` names the volume the model stands in for: AFaM, the
+# mother of the whole absorber. The regions Geant4 needs in order to consult the
+# model are derived from it by walking its subtree and collecting the media,
+# because a region can only ever be "every volume of a given material".
 #
 # The setup is PIPE and ABSO only, which keeps the run short and puts the
 # absorber in the path of everything.
@@ -41,7 +40,7 @@ mkdir -p fast && cd fast
 o2-sim-serial -n ${EVENTS} ${GEN} -e TGeant4 ${MODULES} -o fast \
     --configKeyValues "${COMMON};\
 G4.fastSimModels=toyAbsorber;\
-G4.fastSimRegions=ABSO_AIR_ENVELOPE;\
+G4.fastSimEnvelope=AFaM;\
 G4.fastSimMinEnergy=1.0" > logfast 2>&1
 cd ..