Initialization sequence for actors
==================================


Here is the chronological initialization sequence for actors, mapping the bridge between Python and C++.

Single threaded (ST) Initialization Sequence
--------------------------------------------

1. ``actor_engine.initialize()`` (Python): Python master loop triggers actor configuration before Geant4 builds the geometry.
2. ``InitializeUserInfo()`` & ``InitializeCpp()`` (C++): Extracts parameters from the Python dictionary (e.g., splitting factors, kill volumes) and registers the C++ actor instance.
3. ``g4_RunManager.Initialize()`` (C++): Geant4 constructs the master mass and parallel geometries.
4. ``ConstructSDandField()`` (Python/C++): Geant4 triggers OpenGATE to handle sensitive detectors and biasing operators.
5. ``ConfigureForWorker()`` (C++): The actor looks up the main ``G4LogicalVolume`` and attaches itself (and to all daughter volumes).
6. ``actor_engine.register_actions()`` (Python): Binds the Python actor to the master thread's Tracking, Stepping, Event, and Run action lists.
7. ``StartTracking()`` (C++): Triggered natively by Geant4 when a particle track begins, resetting tracking flags.


Multithreaded (MT) Initialization Sequence
------------------------------------------

1. ``actor_engine.initialize()`` (Python): Executed strictly on the Master Thread to push Python parameters to C++ before workers exist.
2. ``InitializeUserInfo()`` & ``InitializeCpp()`` (C++): Executes on the Master Thread to save variables (must *not* initialize thread-local pointers here).
3. ``g4_RunManager.InitializeWithoutFakeRun()`` (C++): Geant4 builds the master geometry but holds off on worker creation.
4. ``FakeBeamOn()`` (C++): Geant4 officially spawns the worker threads.
5. ``ConstructSDandField()`` (Python/C++): Triggered by Geant4 independently *for every single worker thread*.
6. ``ConfigureForWorker()`` (C++): Called per worker. The actor securely attaches itself to the thread-local instances of the ``G4LogicalVolume``.
7. ``actor_engine.register_actions()`` (Python): Binds the Python actor to the newly created, thread-local Geant4 action lists.
8. ``PreUserTrackingAction()`` (C++): OpenGATE's mandatory MT hook to force tracking initialization (since Geant4 skips native ``StartTracking`` for MT biasing operators).
9. ``StartTracking()`` (C++): Triggered by ``PreUserTrackingAction``. Lazy-initializes the thread-local caches (``threadLocalData.Get()``), instantiates the thread-local operations, and resets flags.