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 theCELER_DISABLE
environment variable as a global option for disabling Celeritas offloading. This is implemented bySimpleOffload
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, theInitialize
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 SPOptical = std::shared_ptr<OpticalCollector>
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 SPOptical const &optical() const
Optical data: null if Celeritas optical physics is disabled.
-
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.
-
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 .
-
static VecG4PD const &supported_offload_particles()
Get a list of all supported particles.
-
static VecG4PD const &default_offload_particles()
Get the list of default particles offloaded in Geant4 applications.
If no user-defined list is provided, this defaults to simulating EM showers.
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.
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.
-
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 VecG4PD const &OffloadParticles() const
Get a vector of particles to be used by Celeritas offloading.
-
inline explicit operator bool() const
Whether the class has been constructed.
-
using SPGeantSd = std::shared_ptr<GeantSd>
-
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 ¶ms)
Construct with shared (MT) params.
-
inline void Initialize(SetupOptions const &options, SharedParams ¶ms)
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&)
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¶
-
inline Logger celeritas::MakeMTLogger(G4RunManager const &rm)¶
Manually create a multithread-friendly logger.
- Deprecated:
Remove in v1.0; replaced by MakeMTSelfLogger
-
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 custom along-step action (i.e., the same stepper is used for 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::CartMapFieldAlongStepFactory, 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.
Fields¶
-
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.
Primary generators¶
-
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 PGPrimaryGeneratorAction : public G4VUserPrimaryGeneratorAction¶
Generate events from a particle gun.
This generates primary particles with energy, position, and direction sampled from distributions specified by the user in
PrimaryGeneratorOptions
.See also
PrimaryGenerator
Physics constructors¶
A Geant4 physics constructor celeritas::SupportedEmStandardPhysics
allows
very fine-grained selection of the EM physics processes supported by Celeritas.
The input options incorporate process and model selection as well as default EM
parameters to send to Geant4.
-
struct GeantPhysicsOptions
Construction options for Geant physics.
These options attempt to default to our closest match to
G4StandardEmPhysics
. They are passed to theEmPhysicsList
andFtfpBert
physics lists to provide an easy way to set up physics options.- Todo:
This will be moved to celeritas::inp
Rename default_cutoff to be consistent (it’s a production cut)
Gamma physics
-
bool compton_scattering = {true}
Enable Compton scattering.
-
bool photoelectric = {true}
Enable the photoelectric effect.
-
bool rayleigh_scattering = {true}
Enable Rayleigh scattering.
-
bool gamma_conversion = {true}
Enable electron pair production.
-
bool gamma_general = {false}
Use G4GammaGeneral instead of individual gamma processes.
Electron and positron physics
-
bool coulomb_scattering = {false}
Enable discrete Coulomb.
-
bool ionization = {true}
Enable e- and e+ ionization.
-
bool annihilation = {true}
Enable positron annihilation.
-
BremsModelSelection brems = {BremsModelSelection::all}
Enable bremsstrahlung and select a model.
-
MevEnergy seltzer_berger_limit = {1e3}
Upper limit for the Seltzer-Berger bremsstrahlung model.
-
MscModelSelection msc = {MscModelSelection::urban}
Enable multiple coulomb scattering and select a model.
Electron/positron MSC requires ionization
-
RelaxationSelection relaxation = {RelaxationSelection::none}
Enable atomic relaxation and select a model.
Physics options
-
int em_bins_per_decade = {7}
Number of log-spaced bins per factor of 10 in energy.
-
bool eloss_fluctuation = {true}
Enable universal energy fluctuations.
-
bool lpm = {true}
Apply relativistic corrections for select models.
-
bool integral_approach = {true}
See
PhysicsParamsOptions::disable_integral_xs
.
Cutoff options
-
MevEnergy min_energy = {0.1 * 1e-3}
Lowest energy of any EM physics process.
-
MevEnergy max_energy = {100 * 1e6}
Highest energy of any EM physics process.
-
double linear_loss_limit = {0.01}
See
PhysicsParamsOptions::linear_loss_limit
.
-
MevEnergy lowest_electron_energy = {0.001}
Tracking cutoff kinetic energy for e-/e+.
-
MevEnergy lowest_muhad_energy = {0.001}
Tracking cutoff kinetic energy for muons/hadrons.
-
bool apply_cuts = {false}
Kill secondaries below the production cut.
-
double default_cutoff = {0.1 * units::centimeter}
Set the default production cut for all particle types [len].
Multiple scattering configuration
-
double msc_range_factor = {0.04}
e-/e+ range factor for MSC models
-
double msc_muhad_range_factor = {0.2}
Muon/hadron range factor for MSC models.
-
double msc_safety_factor = {0.6}
Safety factor for MSC models.
-
double msc_lambda_limit = {0.1 * units::centimeter}
Lambda limit for MSC models [len].
-
double msc_theta_limit = {constants::pi}
Polar angle limit between single and multiple Coulomb scattering.
-
double angle_limit_factor = {1}
Factor for dynamic computation of angular limit between SS and MSC.
-
bool msc_displaced = {true}
Whether lateral displacement is enabled for e-/e+ MSC.
-
bool msc_muhad_displaced = {false}
Whether lateral displacement is enabled for muon/hadron MSC.
-
MscStepLimitAlgorithm msc_step_algorithm = {MscStepLimitAlgorithm::safety}
Step limit algorithm for e-/e+ MSC models.
-
MscStepLimitAlgorithm msc_muhad_step_algorithm{MscStepLimitAlgorithm::minimal}
Step limit algorithm for muon/hadron MSC models.
-
NuclearFormFactorType form_factor = {NuclearFormFactorType::exponential}
Nuclear form factor model for Coulomm scattering.
Public Members
-
GeantMuonPhysicsOptions muon = {GeantMuonPhysicsOptions::deactivated()}
Muon EM physics.
-
bool verbose = {false}
Print detailed Geant4 output.
-
GeantOpticalPhysicsOptions optical = {GeantOpticalPhysicsOptions::deactivated()}
Optical physics options.
Public Static Functions
-
static inline GeantPhysicsOptions deactivated()
Initialize with no physics.
-
class SupportedEmStandardPhysics : public G4VPhysicsConstructor¶
Construct G4EmStandardPhysics processes that are implemented in Celeritas.
This physics list is targeted at HEP experiments and reproduces most of the Geant4 G4EmStandardPhysics.
Limitations:
No support for generic ions
No hadronic EM interactions
Wentzel VI MSC is not supported
No polarized gamma processes
Electron/positron processes:
Processes
Model classes
Pair annihilation
G4eeToTwoGammaModel
Ionization
G4MollerBhabhaModel
Bremsstrahlung (low E)
G4SeltzerBergerModel
Bremsstrahlung (high E)
G4eBremsstrahlungRelModel
Coulomb scattering
G4eCoulombScatteringModel
Multiple scattering (low E)
G4UrbanMscModel
Multiple scattering (high E)
G4WentzelVIModel
Gamma processes:
Processes
Model classes
Compton scattering
G4KleinNishinaCompton
Photoelectric effect
G4LivermorePhotoElectricModel
Rayleigh scattering
G4LivermoreRayleighModel
Gamma conversion
G4PairProductionRelModel
If the
gamma_general
option is enabled, we create a single unifiedG4GammaGeneralProcess
process, which embeds these other processes and calculates a combined total cross section. It’s faster in Geant4 but shouldn’t result in statistically different answers.Muon processes are disabled by default:
Processes
Model classes
Pair production
G4MuPairProductionModel
Ionization (low E, mu-)
G4ICRU73QOModel
Ionization (low E, mu+)
G4BraggModel
Ionization (high E)
G4MuBetheBlochModel
Bremsstrahlung
G4MuBremsstrahlungModel
Coulomb scattering
G4eCoulombScatteringModel
Multiple scattering
G4WentzelVIModel
Note
Prior to version 11.1.0, Geant4 used the
G4BetheBlochModel
for muon ionization between 200 keV and 1 GeV and theG4MuBetheBlochModel
above 1 GeV. Since version 11.1.0, theG4MuBetheBlochModel
is used for all energies above 200 keV.
Physics lists¶
Two physics lists (one using Geant4 hadronics, the other using pure Celeritas) allow setup of EM physics using only processes supported by Celeritas.
-
class EmPhysicsList : public G4VModularPhysicsList¶
Construct highly configurable EM and/or optical physics.
-
class FtfpBertPhysicsList : public G4VModularPhysicsList¶
Construct the FTFP_BERT physics list with configurable EM standard physics.
Sensitive detectors¶
-
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.- Deprecated:
This class should be replaced by a more advanced scoring mechanism.