High level interfaces¶

The high-level integration classes are the easiest way to add Celeritas to a Geant4 application. Under the hood, it contains a singleton class instance that sets up the UI commands (see celeritas::SetupOptionsMessenger), MPI (if configured), and Celeritas logging.

class IntegrationBase

Common interface for integrating Celeritas into user applications.

This implements common functionality for the Celeritas integration classes. The GetParams and GetState methods may only be used during a run with Celeritas offloading enabled. It cannot be accessed before the run manager is created (this requirement may be relaxed in the future).

Tracking manager¶

Using Celeritas to “offload” all electrons, photons, and gammas from Geant4 can be done using the new-ish Geant4 interface G4VTrackingManager implemented by celeritas::TrackingManager. To set up the tracking manager correctly, we recommend using this helper class:

class TrackingManagerConstructor : public G4VPhysicsConstructor¶

Construct a Celeritas tracking manager that offloads EM tracks.

This should be composed with your physics list after it is constructed, before the simulation begins. By default this uses the celeritas::TrackingManagerIntegration helper:

auto* physics_list = new FTFP_BERT;
physics_list->RegisterPhysics(new TrackingManagerConstructor{
    &TrackingManagerIntegration::Instance()});

but for manual integration it can be constructed with a function to get a reference to the thread-local LocalTransporter from the Geant4 thread ID:

auto* physics_list = new FTFP_BERT;
physics_list->RegisterPhysics(new TrackingManagerConstructor{
    shared_params, [](int){ return &local_transporter; });

Note

If Celeritas is globally disabled, it will not add the track manager. If Celeritas is configured to “kill offload” mode (for testing maximum theoretical performance) then the tracking manager will be added but will not send the tracks to Celeritas: it will simply kill them.

The high-level celeritas::TrackingManagerIntegration class should be used in addition to the tracking manager constructor to set up and tear down Celeritas. See Geant4-Celeritas offloading template for a template of adding to a user application.

class TrackingManagerIntegration : public celeritas::IntegrationBase ¶

Simple interface for G4VTrackingManager-based integration.

This singleton integrates both thread-local and global data with the user application. To use this class in your Geant4 application to offload tracks to Celeritas:

Use the TrackingManagerConstructor class to add the Celeritas tracking manager to your physics list.
Use SetOptions to set up options before G4RunManager::Initialize: usually in main for simple applications.
Call BeginOfRunAction and EndOfRunAction from UserRunAction

The CELER_DISABLE environment variable, if set and non-empty, will disable offloading so that Celeritas will not be built nor kill tracks.

The method names correspond to methods in Geant4 User Actions and must be called from all threads, both worker and master.

Todo:: Provide default minimal action initialization classes for user

Public Functions

virtual void BeginOfRunAction(G4Run const *run) final¶: Start the run, initializing Celeritas options.

Public Static Functions

static TrackingManagerIntegration &Instance()¶: Access the public-facing integration singleton.

Fast simulation¶

It is currently not recommended to offload tracks on a per-region basis, since tracks exiting that region remain in Celeritas and on GPU.

class FastSimulationModel : public G4VFastSimulationModel¶

Offload tracks to Celeritas via G4VFastSimulationModel interface.

This class must be constructed locally on each worker thread/task, typically within the application’s concrete implementation of G4VUserDetectorConstruction::ConstructSDandField().

Note that the argument G4Envelope is a type alias to G4Region.

Todo:: Maybe need a helper to create a single fast sim model for multiple regions?

class FastSimulationIntegration : public celeritas::IntegrationBase ¶

Simple interface for G4VTrackingManager-based integration.

This singleton integrates both thread-local and global data with the user application. To use this class in your Geant4 application to offload tracks to Celeritas:

Add the FastSimulationModel to regions of interest.
Use SetOptions to set up options before G4RunManager::Initialize: usually in main for simple applications.
Call BeginOfRunAction and EndOfRunAction from UserRunAction

The CELER_DISABLE environment variable, if set and non-empty, will disable offloading so that Celeritas will not be built nor kill tracks.

The method names correspond to methods in Geant4 User Actions and must be called from all threads, both worker and master.

Public Functions

virtual void BeginOfRunAction(G4Run const *run) final¶: Start the run, initializing Celeritas options.

Public Static Functions

static FastSimulationIntegration &Instance()¶: Access the public-facing integration singleton.

User action¶

For compatibility with older versions of Geant4, you may use the following class to integrate Celeritas by manually intercepting tracks with a UserTrackingAction.

class UserActionIntegration : public celeritas::IntegrationBase ¶

Simple interface for G4VUserTrackingAction-based integration.

This singleton integrates both thread-local and global data with the user application. To use this class in your Geant4 application to offload tracks to Celeritas:

Set up the Options before calling G4RunManager::Initialize
Call BeginOfRunAction and EndOfRunAction from UserRunAction
Call BeginOfEvent and EndOfEvent from UserEventAction
Call PreUserTrackingAction from your UserTrackingAction

The CELER_DISABLE environment variable, if set and non-empty, will disable offloading so that Celeritas will not be built nor kill tracks.

The method names correspond to methods in Geant4 User Actions and must be called from all threads, both worker and master.

Todo:: Provide default minimal action initialization classes for user?

Note

Prefer to use celeritas::TrackingManagerIntegration instead of this class, unless you need support for Geant4 earlier than 11.1.

Public Functions

virtual void BeginOfRunAction(G4Run const *run) final¶: Start the run.

void BeginOfEventAction(G4Event const *event)¶: Send Celeritas the event ID.

void PreUserTrackingAction(G4Track *track)¶: Send tracks to Celeritas if applicable and “StopAndKill” if so.

void EndOfEventAction(G4Event const *event)¶: Flush offloaded tracks from Celeritas.

Public Static Functions

static UserActionIntegration &Instance()¶: Access the singleton.

The celeritas::SimpleOffload class is a slightly lower level interface for offloading tracks to Celeritas in a multithreaded or serial application. The class names correspond to user actions and ActionInitialization. It requires a few app-owned pieces such as celeritas::SharedParams and celeritas::LocalTransporter to be owned by the calling application; the options described below must also be set up and provided.

Deprecated since version v0.6: Use the celeritas::TrackingManagerIntegration class.

class SimpleOffload

Compressed interface for running Celeritas in a multithread Geant4 app.

This class must be a thread-local instance with references to data that exceed the lifetime of the class: e.g. SharedParams can be a global variable, and LocalTransporter can be a global variable with thread_local storage duration.

The CELER_DISABLE environment variable, if set and non-empty, will disable offloading so that Celeritas will not be built nor kill tracks.

The method names correspond to methods in Geant4 User Actions and must be called from all threads, both worker and master.

Deprecated:: Use the UserActionIntegration class instead of this, or manually interface with the SharedParams and LocalTransporter for fine-grained control.

Public Functions

SimpleOffload() = default: Construct with celeritas disabled.

SimpleOffload(SetupOptions const *setup, SharedParams *params, LocalTransporter *local)

Construct from a reference to shared params and local data.

On construction, this will check for the CELER_DISABLE variable and disable offloading if set. Otherwise it will initialize the multithread logging if the run manager is initialized.

inline void Build(SetupOptions const *setup, SharedParams *params, LocalTransporter *local): Lazy initialization of this class on a worker thread.

inline void BuildForMaster(SetupOptions const *setup, SharedParams *params): Lazy initialization of this class on the master thread.

void BeginOfRunAction(G4Run const *run): Initialize celeritas data from setup options.

void BeginOfEventAction(G4Event const *event): Send Celeritas the event ID and reseed the Celeritas RNG.

void PreUserTrackingAction(G4Track *track): Send tracks to Celeritas if applicable and “StopAndKill” if so.

void EndOfEventAction(G4Event const *event): Flush offloaded tracks from Celeritas.

void EndOfRunAction(G4Run const *run): Finalize Celeritas.

explicit operator bool() const: Whether offloading is enabled.

Warning

This is still “false” if this class is used to kill tracks with the CELER_KILL_OFFLOAD option.