Problem definition¶

Celeritas contains several high-level “parameter” classes that allow setup-time access to problem data. These classes all correspond directly to “TrackView” classes (see the developer documentation for details).

class GeoParamsInterface¶

Interface class for accessing host geometry metadata.

This class is implemented by OrangeParams to allow navigation with the ORANGE geometry implementation, VecgeomParams for using VecGeom, and GeantGeoParams for testing with the Geant4-provided navigator.

Subclassed by celeritas::GeantGeoParams, celeritas::GeoParamsSurfaceInterface, celeritas::VecgeomParams

class MaterialParams : public celeritas::ParamsDataInterface<MaterialParamsData>¶

Manage material, element, and nuclide properties.

Materials in Celeritas currently correspond to “material cut couples” in Geant4, i.e. the outer product of geometry model-defined materials and user-defined physics regions.

Todo:

Replace id_to_label etc. with direct access to LabelIdMultiMap

Split into isotope/element/geo material

class ParticleParams : public celeritas::ParamsDataInterface<ParticleParamsData>¶

Data management for Standard Model particle classifications.

This class represents “per-problem” shared data about standard model particles being used.

The ParticleParams is constructed on the host with a vector that combines metadata (used for debugging output and interfacing with physics setup) and data (used for on-device transport). Each entry in the construction is assigned a unique ParticleId used for runtime access. See celeritas::PDGNumber for details on the PDG code used during construction.

class PhysicsParams : public celeritas::ParamsDataInterface<PhysicsParamsData>¶

Manage physics processes and models.

The physics params takes a vector of processes and sets up the processes and models. It constructs data and mappings of data:

particle type and process to tabulated values of cross sections etc,
particle type to applicable processes

During construction it constructs models and their corresponding list of ActionId values, as well as the tables of cross section data. Besides the individual interaction kernels, the physics parameters manage additional actions:

”pre-step”: calculate physics step limits
”along-step”: propagate, apply energy loss, multiple scatter
”range”: limit step by energy loss
”discrete-select”: sample a process for a discrete interaction, or reject due to integral cross sectionl
”integral-rejected”: do not apply a discrete interaction
”failure”: interactor failed to allocate secondaries

class CutoffParams : public celeritas::ParamsDataInterface<CutoffParamsData>¶

Management particle and material cutoffs.

Geant4 provides accessors to its production cuts from its G4MaterialCutsCouple class, which couples cutoff and material data. During import, for simplicity, G4’s production cuts are stored alongside the material information, in ImportPhysMaterial . Since this is a direct import, the cutoff map in ImportPhysMaterial stores only the cuts available in Geant4, i.e. only values for gammas, electrons, positrons, and protons.

In Celeritas, particle cutoff is stored contiguously in a single vector of size num_particles * num_materials, which stores all particle cutoffs for all materials. During import, any particle that is not in Geant4’s list receives a zero cutoff value. This opens the possibility to expand cutoffs in the future, when data is not imported anymore.

The Input structure provides a failsafe mechanism to construct the host/device data.

Some processes (e.g. photoelectric effect, decay) can produce secondaries below the production threshold, while others (e.g. bremsstrahlung, ionization) use the production cut as their instrinsic limit. By default all of these secondaries are transported, even if their energy is below the threshold. If the apply_post_interaction option is enabled, any secondary photon, electron, or positron with energy below the cutoff will be killed (the flag will be ignored for other particle types).

Setting up problems¶

Problem data is specified from applications and the Geant4 user interface using the Input API and loaded through “importers”. Different front ends to Celeritas use different sets of importers.

Standalone execution¶

Standalone execution describes how to set up physics data (either through Geant4 or loaded through an external file) and other problem properties.

struct StandaloneInput¶

Celeritas setup for standalone apps.

The order of initialization and loading follows the member declarations:

System attributes (GPU activation etc.) are set first
Problem info is loaded
Geant4 is initialized (if not using full ROOT data)
Geant4 data is loaded (also if not using full ROOT)
External Geant4 data files (such as EM LOW) are loaded
Optional control/diagnostic overrides are loaded
Events are loaded

The input Problem can be an embedded struct or a path to a file to import.

Todo:: physics_import will be a std::optional<GeantImport> after all the ImportData is merged into Problem .

Standalone inputs must also specify the mechanism for loading primary particles. The events field is a variant that can be one of these structures:

struct PrimaryGenerator¶

Generate from a hardcoded distribution of primary particles.

Todo:

Allow programmatic setting from particle ID as well

Units?

using Particle = std::variant<PDGNumber, ParticleId>; 

struct SampleFileEvents¶: Sample random events from an input file.

struct ReadFileEvents¶: Read all events from the given file.

The primary generator, similar to Geant4’s “particle gun”, has different configuration options:

using celeritas::inp::Events = std::variant<PrimaryGenerator, SampleFileEvents, ReadFileEvents>¶: Mechanism for generating events for tracking.

using celeritas::inp::ShapeDistribution = std::variant<PointShape, UniformBoxShape>¶: Choose a spatial distribution for the primary generator.

using celeritas::inp::AngleDistribution = std::variant<IsotropicAngle, MonodirectionalAngle>¶: Choose an angular distribution for the primary generator.

using celeritas::inp::EnergyDistribution = Monoenergetic ¶: Choose an angular distribution for the primary generator.

struct PointShape¶: Generate at a single point.

struct UniformBoxShape¶: Sample uniformly in a box.

struct IsotropicAngle¶: Generate angles isotropically.

struct MonodirectionalAngle¶: Generate angles in a single direction.

struct Monoenergetic¶: Generate primaries at a single energy value.

User application/framework¶

User applications define the system configuration, as well as what Celeritas physics to enable (via GeantImport). Additional custom physics can be added via the adjuster parameter to set or change any loaded data.

struct FrameworkInput

Describe how to import data into celeritas via an Input data structure.

The order of initialization and loading follows the member declarations:

System attributes (GPU activation etc.) are set
Geant4 data is loaded
External Geant4 data files (such as EM LOW) are loaded
Optional control/diagnostic overrides are loaded
Optional framework-defined adjustments are applied

Public Members

System system: Base system configuration.

GeantImport geant: Configure what data to load from Geant4.

GeantDataImport geant_data: Load external data files.

std::optional<UpdateImport> update: Optionally add diagnostics and control parameters from an external file.

std::function<void(Problem&)> adjuster: User application/framework-defined adjustments.

Importers¶

Import options are read in to load problem input from various sources.

struct FileImport

Options for loading problem data from a ROOT/JSON file.

Public Members

std::string input: Path to the problem input file.

struct GeantImport

Options for importing data from in-memory Geant4.

Todo:: Update GeantImportDataSelection to control what Celeritas processes/particles are offloaded.

Public Members

std::vector<std::string> ignore_processes: Do not use Celeritas physics for the given Geant4 process names.

GeantImportDataSelection data_selection: Only import a subset of available Geant4 data.

struct GeantDataImport

Options for loading cross section data from Geant4 data files.

Todo:: This is not yet used, but it will call LivermorePEReader, SeltzerBergerReader, AtomicRelaxationReader to fill cross section data. Since Geant4 data structures don’t provide access to these, we must read them ourselves.

Defaults:

livermore_dir: uses the G4LEDATA environment variable
particle_dir: uses the G4PARTICLEXS environment variable

Public Members

std::string livermore_dir: Livermore photoelectric data directory (optional)

std::string particle_dir: Particle cross section data directory (optional)

struct UpdateImport

Update control and diagnostic options from an external input file.

This is used in concert with FileImport : the output from another code can be used as input, but overlaid with diagnostic and control/tuning information.

Public Members

bool diagnostics = {true}: Replace existing diagnostics.

bool control = {true}: Replace existing control parameters.

std::string input: Path to the file.

Setup¶

namespace setup¶

Configure Celeritas problems from input data.

This implementation detail is how celeritas::inp data is used to construct all the main Celeritas objects.

Functions

void import(inp::FileImport const&, inp::Problem&)¶: Load from a file.

void import(inp::GeantImport const&, inp::Problem&)¶: Load from Geant4 in memory.

void import(inp::GeantDataImport const&, inp::Problem&)¶: Load from Geant4 data files.

void import(inp::UpdateImport const&, inp::Problem&)¶: Update from another file.

void system(inp::System const &sys)¶

Set up low level system properties.

For Celeritas runs, this should be set up before anything else.