Skip to content

Latest commit

 

History

History
189 lines (143 loc) · 6.84 KB

installation.rst

File metadata and controls

189 lines (143 loc) · 6.84 KB

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.

.. tabularcolumns:: lll
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 :file:`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, and tell Spack to default to building with CUDA support with the command spack config add packages:all:variants:"+cuda cuda_arch=<ARCH>", where <ARCH> is the numeric portion of the CUDA architecture flags.
  • Create the Celeritas development environment with spack env create celeritas scripts/spack.yaml.
  • Install all the dependencies with spack -e celeritas install.

The current Spack environment for full-featured development is:

.. literalinclude:: ../scripts/spack.yaml
   :language: yaml

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., [email protected] and [email protected]), 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 :file:`scripts/cmake-presets/{HOSTNAME}.json` and call scripts/build.sh {preset} to create the symlink, configure the preset, build, and test. See :file:`scripts/README.md` in the code repository for more details.