Detailed interface¶

These classes are usually integrated into UserActions. The SimpleOffload interface above hides the complexity of these classes, or for more complex applications you can choose to use these classes directly instead of it.

class SharedParams

Shared (one instance for all threads) Celeritas problem data.

The CeleritasDisabled accessor queries the CELER_DISABLE environment variable as a global option for disabling Celeritas offloading. This is implemented by SimpleOffload

This should be instantiated on the master thread during problem setup, preferably as a shared pointer. The shared pointer should be passed to a thread-local LocalTransporter instance. At the beginning of the run, after Geant4 has initialized physics data, the Initialize method must be called first on the “master” thread to populate the Celeritas data structures (geometry, physics). InitializeWorker must subsequently be invoked on all worker threads to set up thread-local data (specifically, CUDA device initialization).

Some low-level objects, such as the output diagnostics and Geant4 geometry wrapper, can be created independently of Celeritas being enabled.

Internal use only

using SPGeantSd = std::shared_ptr<GeantSd>: Initialization status and integration mode.

using SPOffloadWriter = std::shared_ptr<detail::OffloadWriter>: Initialization status and integration mode.

using SPOutputRegistry = std::shared_ptr<OutputRegistry>: Initialization status and integration mode.

using SPTimeOutput = std::shared_ptr<TimeOutput>: Initialization status and integration mode.

using SPState = std::shared_ptr<CoreStateInterface>: Initialization status and integration mode.

using SPConstGeantGeoParams = std::shared_ptr<GeantGeoParams const>: Initialization status and integration mode.

using BBox = BoundingBox<double>: Initialization status and integration mode.

inline Mode mode() const: Initialization status and integration mode.

inline SPGeantSd const &hit_manager() const

Hit manager, to be used only by LocalTransporter.

If sensitive detector callback is disabled, the hit manager will be null.

inline SPOffloadWriter const &offload_writer() const: Optional offload writer, only for use by LocalTransporter.

inline SPOutputRegistry const &output_reg() const: Output registry for writing data at end of run.

inline SPTimeOutput const &timer() const: Access the timer.

void set_state(unsigned int stream_id, SPState&&): Let LocalTransporter register the thread’s state.

unsigned int num_streams() const

Lazily obtained number of streams.

Todo:: This is currently needed due to some wackiness with the celer-g4 GeantDiagnostics and initialization sequence. We should remove this: for user applications it should strictly be determined by the run manager/input, and celer-g4 should set it up accordingly.

SPConstGeantGeoParams const &geant_geo_params() const

Lazily created Geant geometry parameters.

Todo:: Remove this for 0.7; it’s only used in GeantSimpleCalo and that should be converted to use make_logical_vol_labels from GeantGeoUtils. Also it can cause segfaults (Geant4 allocators as usual) if called during cleanup.

inline BBox const &bbox() const: Initialization status and integration mode.

Status

static Mode GetMode()

Whether celeritas is disabled, set to kill, or to be enabled.

This gets the value from environment variables and

Todo:: This will be refactored for 0.6 to take a celeritas::inp object and determine values rather than from the environment .

static bool CeleritasDisabled()

Whether celeritas is disabled, set to kill, or to be enabled.

This gets the value from environment variables and

Todo:: This will be refactored for 0.6 to take a celeritas::inp object and determine values rather than from the environment .

static bool KillOffloadTracks()

Whether celeritas is disabled, set to kill, or to be enabled.

This gets the value from environment variables and

Todo:: This will be refactored for 0.6 to take a celeritas::inp object and determine values rather than from the environment .

Construction

SharedParams() = default

Set up Celeritas using Geant4 data.

This is a separate step from construction because it has to happen at the beginning of the run, not when user classes are created. It should be called from the “master” thread (for MT mode) or from the main thread (for Serial), and it must complete before any worker thread tries to access the shared data.

explicit SharedParams(SetupOptions const &options)

Set up Celeritas using Geant4 data.

inline void Initialize(SetupOptions const &options): Helper for making initialization more obvious from user code.

void InitializeWorker(SetupOptions const &options)

On worker threads, set up data with thread storage duration.

Some data that has “static” storage duration (such as CUDA device properties) in single-thread mode has “thread” storage in a multithreaded application. It must be initialized on all threads.

void Finalize()

Clear shared data after writing out diagnostics.

This should be executed exactly once across all threads and at the end of the run.

Accessors

inline SPParams const &Params()

Access Celeritas data.

This can only be called after Initialize.

inline SPConstParams Params() const

Access Celeritas data.

This can only be called after Initialize.

inline VecG4ParticleDef const &OffloadParticles() const: Get a vector of particles supported by Celeritas offloading.

inline explicit operator bool() const: Whether the class has been constructed.

Public Types

enum class Mode

Setup for Celeritas usage.

Values:

enumerator uninitialized

enumerator disabled

enumerator kill_offload

enumerator enabled

enumerator size_

class LocalTransporter

Manage offloading of tracks to Celeritas.

This class must be constructed locally on each worker thread/task/stream, usually as a shared pointer that’s accessible to:

a run action (for initialization),
an event action (to set the event ID and flush offloaded tracks at the end of the event)
a tracking action (to try offloading every track)

Todo:: Rename LocalOffload or something?

Warning

Due to Geant4 thread-local allocators, this class must be finalized or destroyed on the same CPU thread in which is created and used!

Public Functions

LocalTransporter(SetupOptions const &options, SharedParams &params): Construct with shared (MT) params.

inline void Initialize(SetupOptions const &options, SharedParams &params)

Helper for making initialization more obvious from user code.

This gives it some symmetry with Finalize, which is provided as an exception-friendly destructor.

void InitializeEvent(int): Set the event ID and reseed the Celeritas RNG at the start of an event.

void Push(G4Track const&): Convert a Geant4 track to a Celeritas primary and add to buffer.

void Flush(): Transport the buffered tracks and all secondaries produced.

void Finalize()

Clear local data.

This may need to be executed on the same thread it was created in order to safely deallocate some Geant4 objects under the hood…

MapStrReal GetActionTime() const: Get the accumulated action times.

CoreStateInterface const &GetState() const: Access core state data for user diagnostics.

CoreStateInterface &GetState(): Access core state data for user diagnostics.

inline explicit operator bool() const: Whether the class instance is initialized.

Interface utilities¶

Logger celeritas::MakeMTLogger(G4RunManager const &runman)¶

Construct a logger that will redirect Celeritas messages through Geant4.

This logger writes the current thread (and maximum number of threads) in each output message, and sends each message through the thread-local G4cerr.

In the main of your application’s exectuable, set the “process-local” (MPI-aware) logger:

celeritas::self_logger() = celeritas::MakeMTLogger(*run_manager);

class ExceptionConverter¶

Translate Celeritas C++ exceptions into Geant4 G4Exception calls.

This should generally be used when wrapping calls to Celeritas in a user application.

For example, the user event action to transport particles on device could be used as:

void EventAction::EndOfEventAction(const G4Event*)
{
    // Transport any tracks left in the buffer
    celeritas::ExceptionConverter call_g4exception{"celer.event.flush"};
    CELER_TRY_HANDLE(transport_->Flush(), call_g4exception);
}

struct AlongStepFactoryInput¶

Input argument to the AlongStepFactory interface.

When passed to a factory instance, all member data will be set (so the instance will be ‘true’).

Most of these classes have been forward-declared because they simply need to be passed along to another class’s constructor.

class AlongStepFactoryInterface¶

Helper class for emitting an AlongStep action.

Currently Celeritas accepts a single along-step action (i.e., the same stepper is used for both neutral and charged particles, across all energies and regions of the problem). The along-step action is a single GPU kernel that combines the field stepper selection, the magnetic field, slowing-down calculation, multiple scattering, and energy loss fluctuations.

The factory will be called from the thread that initializes SharedParams. Instead of a daughter class, you can provide any function-like object that has the same interface.

Celeritas provides a few “default” configurations of along-step actions in celeritas/alongstep.

Subclassed by celeritas::CylMapFieldAlongStepFactory, celeritas::RZMapFieldAlongStepFactory, celeritas::UniformAlongStepFactory

Classes usable by Geant4¶

These utilities are based on Celeritas data structures and capabilities but are written to be usable both by the celer-g4 app and potential other users.

class GeantSimpleCalo : public celeritas::OutputInterface¶

Manage a simple calorimeter sensitive detector across threads.

The factory should be created in DetectorConstruction or DetectorConstruction::Construct and added to the output parameters. Calling MakeSensitiveDetector will emit a sensitive detector for the local thread and attach it to the logical volumes on the local thread.

class HepMC3PrimaryGenerator : public G4VPrimaryGenerator¶

HepMC3 reader class for sharing across threads.

This class should be shared among threads so that events can be correctly split up between them. It should be called from a user’s primary generator action:

void MyAction::GeneratePrimaries(G4Event* event)
{
    CELER_TRY_HANDLE(generator_->GeneratePrimaryVertex(event),
                     ExceptionConverter("celer.event.generate"));
}

Note

This class assumes that all threads will be reading all events sequentially and that events in the HepMC3 file are numbered sequentially from zero.

class RZMapMagneticField : public G4MagneticField¶: A user magnetic field equivalent to celeritas::RZMapField.

class CylMapMagneticField : public G4MagneticField¶: A user magnetic field equivalent to celeritas::CylMapField.

CylMapFieldParams::Input celeritas::MakeCylMapFieldInput(std::vector<G4double> const &r_grid, std::vector<G4double> const &phi_values, std::vector<G4double> const &z_grid)¶

Generates input for CylMapField params with configurable nonuniform grid dimensions in native Geant4 units, and \(\phi\) should be in the range [0; \(2\times\pi\)].

This must be called after G4RunManager::Initialize as it will retrieve the G4FieldManager’s field to sample it.