Celeritas setup

The setup options help translate the Geant4 physics and problem setup to Celeritas. They are also necessary to set up the GPU offloading characteristics. Future versions of Celeritas will automate more of these settings.

By default, sensitive detectors are automatically mapped from Geant4 to Celeritas using the enabled option of celeritas::SDSetupOptions. If no SDs are present (e.g., in a test problem, or one which has only a “stepping manager” which is not presently compatible with Celeritas), the Celeritas setup will fail with an error like:

*** G4Exception : celer0001
      issued by : accel/detail/GeantSd.cc:210
Celeritas runtime error: no G4 sensitive detectors are defined: set `SetupOptions.sd.enabled` to `false` if this is expected
*** Fatal Exception *** core dump ***

struct SetupOptions

Control options for initializing Celeritas.

The interface for the “along-step factory” (input parameters and output) is described in AlongStepFactoryInterface .

Note

This class will be replaced in v1.0 by celeritas::inp::FrameworkInput .

I/O

std::string geometry_file

GDML filename (optional: defaults to exporting existing Geant4)

std::string output_file = {"celeritas.out.json"}

Filename for JSON diagnostic output, empty to disable.

std::string physics_output_file

Filename for ROOT dump of physics data.

std::string offload_output_file

Filename to dump a ROOT/HepMC3 copy of offloaded tracks as events.

std::string geometry_output_file

Filename to dump a GDML file for debugging inside frameworks.

Celeritas stepper options

size_type max_num_tracks = {}

Number of track “slots” to be transported simultaneously.

size_type max_num_events = {}

Maximum number of events in use (DEPRECATED: remove in v0.7)

size_type max_steps = no_max_steps()

Limit on number of steps per track before killing.

size_type max_step_iters = no_max_steps()

Limit on number of step iterations before aborting.

size_type initializer_capacity = {}

Maximum number of track initializers (primaries+secondaries)

real_type secondary_stack_factor = {3.0}

At least the average number of secondaries per track slot.

size_type auto_flush = {}

Number of tracks to buffer before offloading (if unset: max num tracks)

Physics options

VecString ignore_processes

Do not use Celeritas physics for the given Geant4 process names.

CUDA options

size_type cuda_stack_size = {}

Per-thread stack size (may be needed for VecGeom) [B].

size_type cuda_heap_size = {}

Dynamic heap size (may be needed for VecGeom) [B].

bool action_times = {false}

Sync the GPU at every kernel for timing.

bool default_stream = {false}

Launch all kernels on the default stream for debugging (REMOVED)

Diagnostic setup

std::string slot_diagnostic_prefix

Filename base for slot diagnostics.

std::function<void(CoreParams const&)> add_user_actions

Add additional diagnostic user actions [EXPERIMENTAL].

Public Members

IntAccessor get_num_streams

Set the number of streams (defaults to run manager # threads)

SDSetupOptions sd

Sensitive detector options.

Public Static Functions

static inline constexpr size_type no_max_steps()

Don’t limit the number of steps.

struct SDSetupOptions

Control options for initializing Celeritas SD callbacks.

By default, Celeritas connects to Geant4 sensitive detectors so that it reconstructs full-fidelity hits with all available step information.

• If your problem has no SDs, you must set enabled to false.

• By default, steps that do not deposit energy do not generate any hits.

• To improve performance and memory usage, determine what quantities (time, position, direction, touchable, …) are required by your setup’s sensitive detectors and set all other attributes to false.

• Reconstructing the full geometry status using locate_touchable is the most expensive detector option. Disable it unless your SDs require (e.g.) the volume’s copy number to locate a detector submodule.

• Some reconstructed track attributes (such as post-step material) are currently never set because they are rarely used in practice. Contact the Celeritas team or submit a pull request to add this functionality.

Various attributes on the step, track, and pre/post step points may be available depending on the selected options.

• Disabling track will leave G4Step::GetTrack as nullptr .

• Enabling track will set the Charge attribute on the pre-step.

• Requested post-step data including GlobalTime, Position, KineticEnergy, and MomentumDirection will be copied to the Track when the combination of options is enabled.

• Some pre-step properties (Material and MaterialCutsCouple, and sensitive detector) are always updated. Post-step values for those are not set.

• Track and Parent IDs will never be a valid value since Celeritas track counters are independent from Geant4 track counters. Similarly, special Geant4 user-defined UserInformation and AuxiliaryTrackInformation are never set.

The force_volumes option can be used for unusual cases (i.e., when using a custom run manager) that do not define SDs on the “master” thread. Similarly, the skip_volumes option allows optimized GPU-defined SDs to be used in place of a Geant4 callback. For both options, the FindVolumes helper function can be used to determine LV pointers from the volume names.

Note

These setup options affect only the GeantSd construction that is responsible for reconstructing CPU hits and sending directly to the Geant4 detectors. It does not change the underlying physics.

Note

This class will be replaced in v1.0 by celeritas::inp::SensitiveDetector .

Public Functions

inline explicit operator bool() const

True if SD is enabled.

Public Members

bool enabled = {true}

Call back to Geant4 sensitive detectors.

bool ignore_zero_deposition = {true}

Skip steps that do not deposit energy locally.

bool energy_deposition = {true}

Save energy deposition.

bool step_length = {true}

Save physical step length.

bool locate_touchable = {true}

Set TouchableHandle for PreStepPoint.

bool locate_touchable_post = {true}

Set TouchableHandle for PostStepPoint.

bool track = {true}

Create a track with the dynamic particle type and post-step data.

StepPoint pre

Options for saving and converting beginning-of-step data.

StepPoint post

Options for saving and converting end-of-step data.

std::unordered_set<G4LogicalVolume const*> force_volumes

Manually list LVs that don’t have an SD on the master thread.

std::unordered_set<G4LogicalVolume const*> skip_volumes

List LVs that should not have automatic hit mapping.

struct StepPoint

Public Members

bool direction = {true}

AKA momentum direction.

Helper functions

This function helps find logical volumes from volume names:

std::unordered_set<G4LogicalVolume const*> celeritas::FindVolumes(std::unordered_set<std::string> names)

Find volumes by name for SDSetupOptions.

Example:

setup.sd.force_volumes = FindVolumes({"foo", "bar"});

Magnetic field setup

The magnetic fields defined for Celeritas can be used as Geant4 native magnetic fields (see Classes usable by Geant4).

class UniformAlongStepFactory : public celeritas::AlongStepFactoryInterface

Create an along-step method for a uniform (or zero) field.

The constructor is a lazily evaluated function that must return the field definition and driver configuration. If unspecified, the field is zero.

Todo:

Add a helper function to build from a Geant4 field manager or the new G4FieldSetup

class RZMapFieldAlongStepFactory : public celeritas::AlongStepFactoryInterface

Create an along-step method for a two-dimensional (r-z in the cylindical coordinate system) map field (RZMapField).

class CylMapFieldAlongStepFactory : public celeritas::AlongStepFactoryInterface

Create an along-step method for a three-dimensional (r-phi-z in the cylindical coordinate system) map field (CylMapField).

Macro UI Options

The celeritas::SetupOptionsMessenger, instantiated automatically by the Integration helper classes, provides a Geant4 “UI” macro interface to many of the options.

class SetupOptionsMessenger : public G4UImessenger

Expose setup options through the Geant4 “macro” UI interface.

The following options are exposed in the /celer/ command “directory”:

Command	Description
geometryFile	Override detector geometry with a custom GDML
outputFile	Filename for JSON diagnostic output
physicsOutputFile	Filename for ROOT dump of physics data
offloadOutputFile	Filename for HepMC3/ROOT dump of offloaded tracks
geometryOutputFile	Filename for GDML export
maxNumTracks	Number of tracks to be transported simultaneously
maxNumEvents	Maximum number of events in use
maxNumSteps	Limit on number of step iterations before aborting
maxInitializers	Maximum number of track initializers
secondaryStackFactor	At least the average number of secondaries per track
autoFlush	Number of tracks to buffer before offloading
maxFieldSubsteps	Limit on substeps in field propagator
slotDiagnosticPrefix	Print IDs of particles in all slots (expensive)

The following option is exposed in the /celer/detector/ command “directory”:

Command	Description
enabled	Call back to Geant4 sensitive detectors

If a CUDA/HIP device is available, additional options are available under /celer/device/ (or a DEPRECATED /celer/cuda path, to be removed in v0.7):

Command	Description
stackSize	Set the CUDA per-thread stack size for VecGeom
heapSize	Set the CUDA per-thread heap size for VecGeom
actionTimes	Add timers around every action (may reduce performance)
defaultStream	Launch all kernels on the default stream (DEPRECATED)

Warning

The given SetupOptions should be global or otherwise must exceed the scope of this UI messenger.