Fix/multiphoton event without output

[MateuszBala]

fix(multiphoton): produce a detector response for every event

Branch: fix/multiphoton-event-without-output - based on develop (01658459)
Commits: 2 - fix(multiphoton): skip events without primary vertex quietly,
fix(multiphoton): always run the digitizer at end of event
Files: source/digits_hits/src/GateMultiPhotonAnalysis.cc
Depends on: nothing

Two defects in the same branch of GateMultiPhotonAnalysis::RecordEndOfEvent, one deciding when
an event is reported as an anomaly, the other deciding what happens to digitisation on that path.

Defect 1 - a false warning for the event that closes a run

Every simulation using multianalysis ended with one G4Exception warning about a missing
trajectory container:

*** G4Exception : GateMultiPhotonAnalysisMissingTrajectoryContainer
      issued by : GateMultiPhotonAnalysis::RecordEndOfEvent
GateMultiPhotonAnalysis missing trajectory container for run=0, event=99142.
hasProcessableHits=false. Policy=resilient.

Always one event per run, always with hasProcessableHits=false. The event number matches the
counters written into the ROOT file exactly (total_nb_primaries = 99142,
latest_event_ID = 99142): it is the last event of the run.

GateSourceMgr::PrepareNextEvent generates no vertex once the time limit is exceeded ("m_time >
m_timeLimit. No vertex generated"). Geant4 still processes the event to the end, but there is not
a single track in it - and G4Event::GetTrajectoryContainer() returns a container only once the
first trajectory has been stored. Hence the null pointer. Under the strict policy the same event
would have aborted an otherwise correct simulation.

Fix: at the beginning of RecordEndOfEvent, an event with GetNumberOfPrimaryVertex() == 0
ends quietly - no G4Exception, no increment of the anomaly counters. The condition is strictly
equivalent to the description of the case: no primary vertex means no track, hence neither hits
nor a trajectory container. The warning and the counters are left untouched for the case that
really is an anomaly - an event with hits but without trajectories.

Defect 2 - the digitizer was skipped for the whole event

RecordEndOfEvent returned early when the event had no trajectory container, and the call to the
digitizer stood at the end of the method. An event taking that path produced no singles and no
coincidences at all - the hits were there, but nothing turned them into a detector response.
GateAnalysis places the same call outside its if (!trajectoryContainer) block, so it digitises
regardless.

Fix: a scope guard in an anonymous namespace, ScopedDigitizerRunner, whose destructor calls
RunDigitizersIfNeeded(). It is created once in RecordEndOfEvent and the explicit call at the
end of the method was removed, so the digitizer runs no matter which way the analysis of the event
ends. Writing the call before each return was rejected: there are three of them today and there
may be a fourth tomorrow.

The guard is created after the tracking-mode check, not before it: an unsupported tracking mode
raises a FatalException whose message says explicitly that further processing, digitisation
included, is skipped. That path is left as it was.

Verification

Defect 1 - the same simulation on both builds:

build	MissingTrajectoryContainer warnings	summary Missing trajectory container in ...
before	1	present
after	0	absent

The data is unchanged: 317 154 hits in back-to-back-only-detector before and after, with the
columns eventID, trackID, parentID, nPhantomCompton, nCrystalCompton, nInteractions,
edep and time identical row by row, and total_nb_primaries and latest_event_ID both still
99 142.

make run-single SIM_DIR=simulations/ref-fix/gate-multi-photon-analysis/back-to-back-only-detector
grep -c MissingTrajectoryContainer .../run.log

Defect 2 - the situation does not arise on its own (GATE stores trajectories for all tracks),
so it was produced deliberately: two binaries differing only in this fix, both with
trajectoryContainer = nullptr; inserted right after the container is read, running the same
short PET simulation with Singles enabled:

build	Hits	Singles
before	5 992	0
after	5 992	4 228

No regression in ordinary running: positronium-source-mixed-prompt-with-phantom gives the same
305 207 hits and 216 312 singles as before, and the whole test suite passes.

Scope

One file, one method of the multi-photon analysis module. GateAnalysis and GateFastAnalysis are
untouched; the change makes multianalysis behave like GateAnalysis on both paths.

Details:
https://github.com/MateuszBala/opengate-gate-multiphoton-analysis-verification/blob/main/docs/bugs/bug-14-false-warning-for-empty-event.md
https://github.com/MateuszBala/opengate-gate-multiphoton-analysis-verification/blob/main/docs/bugs/bug-05-digitizer-skipped-without-trajectory-container.md