Run

Design Philosophy

The run category manages collections of events (runs). In a single run the events share the detector implementation, physics conditions and primary generation.

The classes associated with the run category can be considered as the main and higher level application programming interface (API) used in a Geant4 application. A simple application will use concrete classes provided with the toolkit, the developer will provide the detector description a primary generator (possibly using one of the general purpose ones provided with the toolkit), define the physics for the application (the physics list, possibly one of the few provided with the toolkit) and optional user actions to interact with the simulation itself.

In few cases it is however necessary to modify the default behaviour of one or more classes in this category to allow for a user-customisation. As an example the class G4MTRunManager extends the basic run-manager class to take into account event level parallelism via multi-threading.

During a run some states of the application are invariant and cannot be modified: the physics list (i.e. the list of processes attached to each particle) and the detector layout (note that some geometry primitives allow for changing parameters during the event run: parameterisations. However technically the class instances representing the detector layout do not change during a run).

Class Design

The relevant classes for the run category are shown here. This show, in particular, the relation between classes for the case of a multi-threaded application. For a sequential application the diagram is simplified since no G4WorkerRunManager class exist and G4MTRunManager is replaced by G4RunManager:

Class diagram

Fig. 1 Class diagram for main run category classes.

For a description of multi-threading functionality refer to Parallelism in : multi-threading capabilities chapter.

One of the main functions of the run category is to control the life-cycle of a Geant4 application, again with reference to the case of a multi-threaded application the following schema describes it:

Simplified life cycle

Fig. 2 Life cycle of a Geant4 application and main run category classes.

A list of the main classes for the category is provided:

  • G4Run - This class represents a run. An object of this class is constructed and deleted by G4RunManager.

  • G4RunManager - the run controller class. Users must register detector construction, physics list and primary generator action classes to it. G4RunManager or a derived class must be a singleton. This class provides several virtual methods that can be used to define user-specific behaviour for a Geant4 application.

  • G4RunManagerKernel - provides control of the Geant4 kernel. This class is constructed by G4RunManager. This class does not provide virtual methods and user should not sub-class from it. The application G4RunManager should own an instance of a G4RunManagerKernel singleton.

  • G4{MT,Worker}RunManager[Kernel] - specialised versions to provide a multi-threading enabled application. Refer to chapter Parallelism in : multi-threading capabilities for additional information.

  • G4VUserDetectorConstruction - pure virtual base class that represents the simulation setup.

  • G4VUserParallelWorld - pure virtual base class of the user’s parallel world.

  • G4VUserPhysicsList - pure virtual base class for a physics list.

  • G4VUserPrimaryGeneratorAction - pure virtual class used by user to define the primary generation.

  • G4VModularPhysicsList - Pure virtual class to construct a physics list from G4VPhysicsConstructor. More modern and modular approach preferred in current versions of pre-packaged physics lists.

  • G4UserRunAction - user action class for run. Instantiate user-derived G4Run and provides user-hooks for begin and end of run.

  • G4UserWorkerInitialization and G4UserWorkerThreadInitialization - define here the concrete behaviour for threading model. Both classes provide several virtual methods that can be modified in derived classes.

  • G4VUserActionInitialization - pure virtual class used by user to instantiate concrete instances of the user-actions.

  • G4WorkerThread - this class encapsulates thread-specific data.

  • G4RNGHelper - helper class to register and use RNG seeds. Used by MT applications to guarantee reproducibility.