Applications

Standalone simulation app (celer-sim)

The celer-sim application is the primary means of running EM test problems for independent validation and performance analysis. See Celeritas for standalone profiling for an example.

Usage:

Run standalone Celeritas


./celer-sim [OPTIONS] [filename] [SUBCOMMANDS]


POSITIONALS:
  filename TEXT:(FILE) OR ('-' for stdin/stdout)
                              Input JSON

OPTIONS:
  -h,     --help              Print this help message and exit
  -v,     --version           Display program version information and exit
          --config            DEPRECATED: use 'config' subcommand instead
          --dump-default      DEPRECATED: use 'default' subcommand instead
          --device            DEPRECATED: use 'device' subcommand instead

SUBCOMMANDS:
  config                      Show configuration
  default                     Show default input
  device                      Show device information
  update                      Convert a deprecated input JSON file

• input.json is the path to the input file, or - to read the JSON from stdin.

• The config option prints the contents of the ["system"]["build"] diagnostic output. It includes configuration options and the version number.

• The device option prints diagnostic output for the default GPU, similar to the output from the deviceQuery CUDA example.

• The default option prints the default options for the execution. Not all variables will be shown, because some are conditional on others.

Input

The input parameters are documented in the Input section, including the standalone execution input described in Standalone execution. See JSON input for standalone apps for the JSON encoding conventions and minimal standalone input examples.

In addition to these input parameters, Environment variables can be specified to change the program behavior.

Output

The primary output from celer-sim is a JSON object that includes several levels of diagnostic and result data. The JSON output is written either to the configured output file or, if no output file is specified, to stdout. When writing to stdout, the JSON output should be the only data sent there, so it is suitable for piping directly into other executables such as Python or jq.

Additional user-oriented output is sent to stderr via the Logger facility (see I/O and Logging).

Standalone optical simulation app (celer-optical)

The celer-optical application runs optical photon problems for independent validation and performance analysis. It is similar to celer-sim, but it executes only the optical photon transport loop. See Celeritas optical simulation for standalone profiling for an example.

Usage:

Run a standalone Celeritas optical simulation


./celer-optical [OPTIONS] [filename] [SUBCOMMANDS]


POSITIONALS:
  filename TEXT:(FILE) OR ('-' for stdin/stdout)
                              Input JSON

OPTIONS:
  -h,     --help              Print this help message and exit
  -v,     --version           Display program version information and exit

SUBCOMMANDS:
  config                      Show configuration
  default                     Show default input
  device                      Show device information

• input.json is the path to the input file, or - to read the JSON from stdin.

• The config option prints the contents of the ["system"]["build"] diagnostic output. It includes configuration options and the version number.

• The device option prints diagnostic output for the default GPU, similar to the output from the deviceQuery CUDA example.

• The default option prints the default options for the execution. Not all variables will be shown, because some are conditional on others.

Input

The input parameters are documented in the Input section, including the optical standalone execution input celeritas::inp::OpticalStandaloneInput described in Standalone execution. See JSON input for standalone apps for the JSON encoding conventions and minimal standalone input examples.

Output

Like celer-sim, the output from celer-optical is a JSON object containing diagnostic and result data which can be written either to the configured output file or to stdout.

Integrated Geant4 application (celer-g4)

The celer-g4 app is a Geant4 application that offloads EM tracks to Celeritas. It takes as input a GDML file with the detector description and sensitive detectors marked via an auxiliary annotation. The input particles must be specified with a HepMC3-compatible file or with a JSON-specified “particle gun.” See Celeritas+Geant4 for verification for an example.

Usage:

usage: ./celer-g4 {input}.json
       ./celer-g4 -
       ./celer-g4 [--help|-h]
       ./celer-g4 --version
       ./celer-g4 --dump-default
Environment variables:
  G4FORCE_RUN_MANAGER_TYPE: MT or Serial
  G4FORCENUMBEROFTHREADS: set CPU worker thread count
  CELER_DISABLE: nonempty disables offloading
  CELER_DISABLE_DEVICE: nonempty disables CUDA
  CELER_DISABLE_ROOT: nonempty disables ROOT I/O
  CELER_KILL_OFFLOAD: nonempty kills offload tracks
  CELER_LOG: global logging level
  CELER_LOG_LOCAL: thread-local logging level

Input

Physics is set up using the top-level physics_option key in the JSON input, corresponding to Physics setup. The magnetic field is specified with a combination of the field_type, field, and field_file keys, and detailed field driver configuration options are set with field_options corresponding to the FieldOptions class in Field.

Deprecated since version v0.5: The macro file usage is in the process of being replaced by JSON input for improved automation. The input parameters will be documented for version 1 in the Input section and Standalone execution. Until then, refer to the source code at app/celer-g4/RunInput.hh .

The input is a Geant4 macro file for executing the program. Celeritas defines several macros in the /celer and (if CUDA is available) /celer/cuda/ directories: see High level interfaces for a listing.

The celer-g4 app defines several additional configuration commands under /celerg4:

Table 1 Geant4 UI commands defined by celer-g4.

Command	Description
geometryFile	Filename of the GDML detector geometry
eventFile	Filename of the event input read by HepMC3
rootBufferSize	Buffer size of output root file [bytes]
writeSDHits	Write a ROOT output file with hits from the SDs
stepDiagnostic	Collect the distribution of steps per Geant4 track
stepDiagnosticBins	Number of bins for the Geant4 step diagnostic
fieldType	Select the field type [rzmap|uniform]
fieldFile	Filename of the rz-map loaded by RZMapFieldInput
magFieldZ	Set Z-axis magnetic field strength (T)

In addition to these input parameters, Environment variables can be specified to change the program behavior.

Output

The ROOT “MC truth” output file, if enabled with the command above, contains hits from all the sensitive detectors.