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. However, any combination of these requirements can be omitted to enable limited development on experimental HPC systems or personal machines with fewer available components.

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
nljson	Runtime	Simple text-based I/O for diagnostics and program setup
Open MPI	Runtime	Shared-memory parallelism
ROOT	Runtime	Input and output
SWIG	Runtime	Low-level Python wrappers
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

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).

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 cxxstd=17"
    - git
    - git-lfs
    - "googletest@1.10:"
    - hepmc3
    - ninja
    - nlohmann-json
    - mpi
    - "python@3.6:"
    - py-breathe
    - py-furo
    - py-sphinx
    - py-sphinxcontrib-bibtex
    - "root@6.24: cxxstd=17"
    - "swig@4.1:"
    - "vecgeom@1.2.4: +gdml cxxstd=17"
  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:
      providers:
        blas: [openblas]
        lapack: [openblas]
        mpi: [openmpi]
      # Uncomment to enable cuda build or run within the spack env:
      # spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=<ARCH>"
      variants: cxxstd=17 # +cuda cuda_arch=<ARCH>

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.