Developer guide: Progress Hook Architecture

Overview

The Progress Hook system provides periodic runtime execution monitoring during Geant4 event loops in OpenGATE.

Architecture

The progress hook bridges C++ event generation loops with Python execution contexts:

1. C++ Side (`GateSourceManager`): - Holds fProgressReportCallback (py::function) and fProgressReportInterval (in real seconds). - In GateSourceManager::GeneratePrimaries(), CheckProgressReport() is invoked on event generation. - Evaluates elapsed real wall-clock time (std::chrono::steady_clock). - Acquires the Python GIL (py::gil_scoped_acquire) before invoking the Python callback safely. - In MT mode, CheckProgressReport() runs on worker thread managers to deliver periodic updates.

2. Python Engine (`SourceEngine` in `engines.py`): - In SourceEngine.start(), checks sim.progress_hook. - Attaches sim.progress_hook (and sim.progress_hook_interval) to Thread 0’s source manager (g4_thread_source_managers[0] in MT mode, or g4_master_source_manager in ST mode). - Upon simulation completion, invokes sim.progress_hook(“completed”).

3. User Hooks Module (`userhooks.py`): - gate.progress_status(filename, interval) is a factory function creating a progress status reporter callback. - Aggregates total events across g4_master_source_manager and all worker managers in g4_thread_source_managers. - Computes elapsed time, progress ratio, and current simulation time before dumping the JSON payload.