Installation¶

Celeritas is designed to be easy to install for a multitude of use cases.

Dependencies¶

Celeritas is built using modern CMake. It has multiple dependencies to operate as a full-featured code, but each dependency can be individually disabled as needed.

The code requires external dependencies to build with full functionality, but none of them need to be installed externally for the code to work. Most can be omitted entirely to enable limited development on experimental HPC systems or personal machines with fewer available components. Items with an asterisk in the category below will be fetched from the internet if required but not available on the user’s system.

Component	Category	Description
CUDA	Runtime	GPU computation
Geant4	Runtime	Preprocessing physics data for a problem input
G4EMLOW	Runtime	EM physics model data
HepMC3	Runtime	Event input
HIP	Runtime	GPU computation
libpng	Runtime	PNG output for raytracing
nljson	Runtime*	Simple text-based I/O for diagnostics and program setup
Open MPI	Runtime	Shared-memory parallelism
ROOT	Runtime	Input and output
VecGeom	Runtime	On-device navigation of GDML-defined detector geometry
Breathe	Docs	Generating code documentation inside user docs
Doxygen	Docs	Code documentation
Sphinx	Docs	User documentation
sphinxbib	Docs	Reference generation for user documentation
clang-format	Development	Code formatting enforcement
CMake	Development	Build system
Git	Development	Repository management
GoogleTest	Development*	Test harness
Perfetto	Development*	CPU profiling

Ideally you will build Celeritas with all dependencies to gain the full functionality of the code, but there are circumstances in which you may not have (or want) all the dependencies or features available. By default, the CMake code in Celeritas queries available packages and sets several CELERITAS_USE_{package} options based on what it finds, so you have a good chance of successfully configuring Celeritas on the first go. Some optional features will error out in the configure if their required dependencies are missing, but they will update the CMake cache variable so that the next configure will succeed (with that component disabled).

Configuration options¶

The interactive ccmake tool is highly recommended for exploring the Celeritas configuration options, since it provides both documentation and an easy way to toggle through all the valid options.

CELERITAS_USE_{package}: Enable features of the given dependency. The configuration will fail if the dependent package is not found.
CELERITAS_BUILD_{DOCS|TESTS}: Build optional documentation and/or tests.
CELERITAS_CORE_GEO: Select the geometry package used by the Celeritas stepping loop. Valid options include VecGeom, Geant4, and ORANGE. There are limits on compatibility: Geant4 is not compatible with GPU-enabled or OpenMP builds, and VecGeom is not compatible with HIP.
CELERITAS_CORE_RNG: Select the pseudorandom number generator. Current options are platform-dependent implementations of XORWOW.
CELERITAS_DEBUG: Enable detailed runtime assertions. These will slow down the code considerably, especially on GPU builds.
CELERITAS_OPENMP: Choose between no multithreaded OpenMP parallelism (disabled), event-level parallelism for the celer-sim app, and track-level parallelism. OpenMP should be disabled with multithreaded Geant4 but will work correctly with single-threaded applications.
CELERITAS_REAL_TYPE: Choose between double and float real numbers across the codebase. This is currently experimental.
CELERITAS_UNITS: Choose the native Celeritas unit system: see the unit documentation.

Celeritas libraries (generally) use CMake-provided default properties. These can be changed with standard CMake variables such as BUILD_SHARED_LIBS to enable shared libraries, CMAKE_POSITION_INDEPENDENT_CODE, etc.

Toolchain installation¶

The recommended way to install dependencies is with Spack, an HPC-oriented package manager that includes numerous scientific packages, including those used in HEP. Celeritas includes a Spack environment at scripts/spack.yaml that describes the code’s full suite of dependencies (including testing and documentation). To install these dependencies:

Clone and load Spack following its getting started instructions.
If using CUDA: run spack external find cuda to inform Spack of the existing installation
Create the Celeritas development environment with spack env create celeritas scripts/spack.yaml.
Tell Spack to default to building with CUDA support with the command spack -e celeritas config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=<ARCH>", where <ARCH> is the numeric portion of the CUDA architecture flags.
Install all the dependencies with spack -e celeritas install.

The current Spack environment for full-featured development is:

spack:
  specs: 
    - cmake
    - doxygen
    - "geant4@11"
    - git
    - git-lfs
    - "googletest@1.10:"
    - hepmc3
    - libpng
    - ninja
    - nlohmann-json
    - mpi
    - "python@3.6:"
    - py-breathe
    - py-furo
    - py-sphinx
    - py-sphinxcontrib-bibtex
    - py-sphinxcontrib-mermaid
    - "root@6.28:"
    - "vecgeom@1.2.4: +gdml"
  view: true
  concretizer:
    unify: true
  packages:
    root:
      # Note: ~gsl and ~math are removed because dd4hep requires them
      variants: ~aqua ~davix ~examples ~opengl ~x ~tbb
    all:
      # Note: for CUDA support run this command in your environment:
      # spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=<ARCH>"
      variants: cxxstd=17

With this environment (with CUDA enabled), all Celeritas tests should be enabled and all should pass. Celeritas is build-compatible with older versions of some dependencies (e.g., Geant4@10.6 and VecGeom@1.2.2), but some tests may fail, indicating a change in behavior or a bug fix in that package. Specifically, older versions of VecGeom have shapes and configurations that are incompatible on GPU with new CMS detector descriptions.

Building Celeritas¶

Once the Celeritas Spack environment has been installed, set your shell’s environment variables (PATH, CMAKE_PREFIX_PATH, …) by activating it.

To clone the latest development version of Celeritas:

$ git clone https://github.com/celeritas-project/celeritas.git

or download it from the GitHub-generated zip file.

, you can configure, build, and test using the provided helper script:

$ cd celeritas
$ spack env activate celeritas
$ ./scripts/build.sh base

or manually with:

$ cd celeritas
$ spack env activate celeritas
$ mkdir build && cd build
$ cmake ..
$ make && ctest

CMake Presets¶

To manage multiple builds with different configure options (debug or release, VecGeom or ORANGE), you can use the CMake presets provided by Celeritas via the CMakePresets.json file for CMake 3.21 and higher:

$ cmake --preset=default

The three main options are “minimal”, “default”, and “full”, which all set different expectations for available dependencies.

Note

If your CMake version is too old, you may get an unhelpful message:

CMake Error: Could not read presets from celeritas: Unrecognized "version"
field

which is just a poor way of saying the version in the CMakePresets.json file is newer than that version knows how to handle.

If you want to add your own set of custom options and flags, create a CMakeUserPresets.json file or, if you wish to contribute on a regular basis, create a preset at scripts/cmake-presets/HOSTNAME.json and call scripts/build.sh {preset} to create the symlink, configure the preset, build, and test. See scripts/README.md in the code repository for more details.