Problem setup¶

Virtually all attributes of the problem and its execution are defined through the Problem input class, which is set up in part by the user and in part by external applications as directed by the user.

struct Problem

Celeritas problem input definition.

This should specify all the information necessary to track particles within Celeritas for offloading or standalone execution. (It does not contain system configuration such as GPU, or event/offload information.)

Multiple problems can be run independently across the same program execution.

Eventually this class and its daughters will subsume all the data in celeritas/io/ and all the input options from Models, Processes, Params, and other classes that are not implementation details.

After loading, the struct will be able to be serialized to ROOT or JSON or some other struct for reproducibility.

Public Members

Model model: Geometry, material, and region definitions.

Physics physics: Physics models and options.

Field field: Set up the magnetic field.

Scoring scoring: Manage scoring of hits and other quantities.

Tracking tracking: Tuning options that affect the physics.

Control control: Low-level performance tuning and simulation control options.

Diagnostics diagnostics: Monte Carlo tracking, performance, and debugging diagnostics.

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 adjust member 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 imported
External Geant4 data files (such as EM LOW) are loaded
Optional framework-defined adjustments are applied

Todo:

Add an input option for kill_offload/disable

Public Members

System system: Base system configuration.

PhysicsFromGeant physics_import: Configure what data to load from Geant4.

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

Loading data into Celeritas¶

Import options are read in to load problem input from Geant4 and other sources.

struct PhysicsFromFile

Load physics data from a ROOT file.

Todo:: This should be replaced with a “ProblemFromFile” that supports ROOT or JSON. Currently it loads directly into ImportData as a stopgap. We may also want to completely replace ROOT.

Public Members

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

struct PhysicsFromGeant

Options for importing data from in-memory Geant4.

Todo:

Use “offload particle types” (variant: grouping, G4PD*, PDG)
Load all processes applicable to offload particles
Determine particle list from process->secondary mapping
Always load interpolation flags; clear them elsewhere if user wants to
Load all materials visible to geometry (and eventually fix PhysMatId vs GeoMatId)

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 PhysicsFromGeantFiles

Options for loading cross section data from Geant4 data files.

Todo:: Since Geant4 data structures don’t provide access to these, we must read them ourselves. Maybe add accessors to Geant4 and eliminate these/roll them upstream?

Defaults:

livermore_dir: usually $G4LEDATA/livermore/phot_epics2014
neutron_dir: usually $G4PARTICLEXSDATA/neutron
fluor_dir: usually $G4LEDATA/fluor
auger_dir: usually $G4LEDATA/auger

Public Members

std::string livermore_dir: Livermore photoelectric data directory.

std::string neutron_dir: Neutron cross section data directory.

std::string fluor_dir: Fluorescence transition probabilities and subshells.

std::string auger_dir: Auger transition probabilities.

Standalone execution¶

Standalone execution describes how to set up Geant4 physics and what events to run.

struct StandaloneInput

Celeritas setup for standalone apps.

The order of initialization and loading (see celeritas::setup::Problem ) 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.

Public Members

System system: System attributes.

Problem problem: Base problem options and input data.

std::optional<GeantSetup> geant_setup: Set up Geant4 (if all the data isn’t already loaded into Problem)

std::variant<PhysicsFromGeant, PhysicsFromFile> physics_import: Whether using Geant4 or loading from ROOT.

Events events: Primary particles.

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:: move num_events to StandaloneInput

Subclassed by celeritas::inp::CorePrimaryGenerator

Public Functions

inline explicit operator bool() const: True if there’s at least one primary.

Public Members

size_type num_events = {}: Number of events to generate.

size_type primaries_per_event = {}: Number of primaries per event.

ShapeDistribution shape: Distribution for sampling spatial component (position)

AngleDistribution angle: Distribution for sampling angular component (direction)

EnergyDistribution energy: Distribution for sampling source energy.

struct SampleFileEvents

Sample random events from an input file.

Todo:: move num_events to StandaloneInput

Public Members

size_type num_events = {}: Total number of events to sample.

size_type num_merged = {}: File events per sampled event.

std::string event_file: ROOT file input.

unsigned int seed = {}: Random number generator seed.

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<CorePrimaryGenerator, SampleFileEvents, ReadFileEvents>¶: Mechanism for generating events for tracking.

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

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

using celeritas::inp::EnergyDistribution = MonoenergeticDistribution ¶: Choose an energy distribution for the primary generator.

struct PointDistribution: Generate at a single point.

struct UniformBoxDistribution: Sample uniformly in a box.

struct IsotropicDistribution: Generate angles isotropically.

struct MonodirectionalDistribution: Generate angles in a single direction.

struct MonoenergeticDistribution: Generate primaries at a single energy value.

System¶

Some low-level system options, such as enabling GPU, are set up once per program execution. They are not loaded by the Problem definition but are used by the standalone/framework inputs.

struct System

Set up system parameters defined once at program startup.

Todo:

Add OpenMP options

Add MPI options

Add Logger verbosity

Public Members

std::map<std::string, std::string> environment: Environment variables used for program setup/diagnostic.

std::optional<Device> device: Optional: activate GPU.

struct Device

Set up GPU capabilities and debugging options.

Stream sharing and synchronization might be helpful for debugging potential race conditions or improving timing accuracy (at the cost of reducing performance).

The CUDA heap and stack sizes may be needed for VecGeom, which has dynamic resource requirements.

Todo:: Move the CELER_DEVICE_ASYNC environment variable here

Public Members

size_type stack_size = {}: Per-thread CUDA stack size (ignored if zero) [B].

size_type heap_size = {}: Global dynamic CUDA heap size (ignored if zero) [B].