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.

See also

celeritas::UserActionIntegration

See also

celeritas::TrackingManagerIntegration

Note

For developers: this and the integration daughters all share common data in detail::IntegrationSingleton.

Subclassed by celeritas::FastSimulationIntegration, celeritas::TrackingManagerIntegration, celeritas::UserActionIntegration

Public Functions

void SetOptions(SetupOptions &&opts)

Set options before starting the run.

This captures the input to indicate that options cannot be modified after this point.

void BuildForMaster()

Initialize during ActionInitialization on non-worker thread in MT mode.

void Build()

Initialize during ActionInitialization on a worker thread or serial mode.

We guard against Build being called from BuildForMaster since we might add worker-specific code here.

void EndOfRunAction(G4Run const *run)

End the run.

CoreParams const &GetParams()

Access Celeritas shared params.

CoreStateInterface &GetState()

Access THREAD-LOCAL Celeritas core state data for user diagnostics.

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 Build and BuildForMaster from UserActionInitialization

  • 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 Build and BuildForMaster from UserActionInitialization

  • 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 Build and BuildForMaster from UserActionInitialization

  • 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.