The Celeritas project implements HEP detector physics on GPU accelerator hardware with the ultimate goal of supporting the massive computational requirements of the HL-LHC upgrade.
Most of the Celeritas documentation is readable through the codebase through a
combination of static RST documentation and Doxygen-markup
comments in the source code itself. The full Celeritas user
documentation (including selected code documentation incorporated
by Breathe) and the Celeritas code documentation are mirrored on
our GitHub pages site. You can generate these yourself (if the necessary
prerequisites are installed) by
setting the CELERITAS_BUILD_DOCS=ON configuration option and running ninja doc (user) or ninja doxygen (developer).
The easiest way to install Celeritas as a library/app is with Spack:
- Follow these steps to install Spack.
# Install Spack
git clone -c feature.manyFiles=true --depth=2 https://github.com/spack/spack.git
# Add Spack to the shell environment
# For bash/zsh/sh (See [spack-start] for other shell)
. spack/share/spack/setup-env.sh- Install Celeritas with
spack install celeritas
```console
- Add the Celeritas installation to your `PATH` with:
```console
spack load celeritasTo install a GPU-enabled Celeritas build, you might have to make sure that VecGeom is also built with CUDA
support if installing celeritas+vecgeom, which is the default geometry.
To do so, set Spack up its CUDA usage:
. spack/share/spack/setup-env.sh
# Set up CUDA
$ spack external find cuda
# Optionally set the default configuration. Replace "cuda_arch=80"
# with your target architecture
$ spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=80"and install Celeritas with this configuration:
$ spack install celeritasIf Celeritas was installed with a different configuration do
$ spack install --fresh celeritasIf you need to set a default configuration
$ spack install celeritas +cuda cuda_arch=80Then see the "Downstream usage as a library" section of the installation documentation for how to use Celeritas in your application or framework.
Since Celeritas is still under heavy development and is not yet full-featured for downstream integration, you are likely installing it for development purposes. The installation documentation has a complete description of the code's dependencies and installation process for development.
As an example, if you have the Spack package manager installed and want to do development on a CUDA system with Volta-class graphics cards, execute the following steps from within the cloned Celeritas source directory:
# Set up CUDA (optional)
$ spack external find cuda
# Install celeritas dependencies
$ spack env create celeritas scripts/spack.yaml
$ spack env activate celeritas
$ spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=80"
$ spack install
# Configure, build, and test
$ ./build.sh baseIf you don't use Spack but have all the dependencies you want (Geant4,
googletest, VecGeom, etc.) in your CMAKE_PREFIX_PATH, you can configure and
build Celeritas as you would any other project:
$ mkdir build && cd build
$ cmake ..
$ make && ctestCeleritas guarantees full compatibility and correctness only on the combinations of compilers and dependencies tested under continuous integration:
- Compilers:
- GCC 8.4, 12.3
- Clang 10.0, 15.0
- GCC 11.3 + NVCC 11.8
- HIP-Clang 15.0
- Dependencies:
- Geant4 11.0.3
- VecGeom 1.2.5
Partial compatibility and correctness is available for an extended range of Geant4:
- 10.5-10.7: no support for tracking manager offload
- 11.0: no support for fast simulation offload
- 11.1-11.2: [no support for default Rayleigh scattering cross section](see #1091)
Since we compile with extra warning flags and avoid non-portable code, most other compilers should work. The full set of configurations is viewable on CI platform GitHub Actions). Compatibility fixes that do not cause newer versions to fail are welcome.
See the contribution guide for the contribution process, the development guidelines for further details on coding in Celeritas, and the administration guidelines for community standards and roles.
| Directory | Description |
|---|---|
| app | Source code for installed executable applications |
| cmake | Implementation code for CMake build configuration |
| doc | Code documentation and manual |
| example | Example applications and input files |
| external | Automatically fetched external CMake dependencies |
| scripts | Development and continuous integration helper scripts |
| src | Library source code |
| test | Unit tests |
If using Celeritas in your work, we ask that you cite the following article:
Johnson, Seth R., Amanda Lund, Philippe Canal, Stefano C. Tognini, Julien Esseiva, Soon Yung Jun, Guilherme Lima, et al. 2024. “Celeritas: Accelerating Geant4 with GPUs.” EPJ Web of Conferences 295:11005. https://doi.org/10.1051/epjconf/202429511005.
See also its DOECode registration:
Johnson, Seth R., Amanda Lund, Soon Yung Jun, Stefano Tognini, Guilherme Lima, Philippe Canal, Ben Morgan, Tom Evans, and Julien Esseiva. 2022. “Celeritas.” https://doi.org/10.11578/dc.20221011.1.
A continually evolving list of works authored by (or with content authored by) core team members is continually updated at our publications page and displayed on the official project web site.
