Merge branch 'develop' of github.com:celeritas-project/celeritas into…

… RefactorOpticalMaterials

.clang-tidy

@@ -9,6 +9,7 @@ Checks: |
   -performance-avoid-endl
   -performance-unnecessary-value-param
   -performance-enum-size
+  -performance-noexcept-destructor
   cppcoreguidelines-*
   -cppcoreguidelines-owning-memory
   -cppcoreguidelines-narrowing-conversions
@@ -25,21 +26,28 @@ Checks: |
   -cppcoreguidelines-noexcept-swap
   -cppcoreguidelines-noexcept-move-operations
   -cppcoreguidelines-noexcept-destructor
+  -cppcoreguidelines-virtual-class-destructor
+  -cppcoreguidelines-c-copy-assignment-signature
+  -cppcoreguidelines-missing-std-forward
+  -cppcoreguidelines-special-member-functions
   bugprone-*
   -bugprone-sizeof-expression
   -bugprone-narrowing-conversions
   -bugprone-macro-parentheses
   -bugprone-easily-swappable-parameters
   -bugprone-implicit-widening-of-multiplication-result
+  -bugprone-exception-escape
 WarningsAsErrors: '*'
 CheckOptions:
   cppcoreguidelines-macro-usage.CheckCapsOnly: true
   cppcoreguidelines-avoid-do-while.IgnoreMacros: true
   cppcoreguidelines-rvalue-reference-param-not-moved.IgnoreNonDeducedTemplateTypes: true
   cppcoreguidelines-rvalue-reference-param-not-moved.AllowPartialMove: true
+  cppcoreguidelines-special-member-functions.AllowSoleDefaultDtor: true
   cppcoreguidelines-avoid-non-const-global-variables.AllowInternalLinkage: true
   performance-move-const-arg.CheckTriviallyCopyableMove: false
   performance-move-const-arg.CheckMoveToConstRef: false
-HeaderFilterRegex: ''
+
+HeaderFilterRegex: '(example|app|src/(accel|celeritas|corecel|orange|geocel))/.*\.hh$'
 FormatStyle: file
 ...

.github/workflows/build-spack.yml

@@ -63,7 +63,7 @@ jobs:
       - name: Check out Celeritas
         uses: actions/checkout@v4
         with:
-          fetch-depth: 383
+          fetch-depth: ${{format('{0}', matrix.special != 'clang-tidy' && 383 || 0)}}
           fetch-tags: true # to get version information
       - name: Setup Spack
         uses: spack/setup-spack@0ce61628ed8a32a5664cf01a0e0b5a4834a3b413 # 2024/03
@@ -135,15 +135,35 @@ jobs:
             test -n "${G4LEDATA}"
           fi
           cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE
+      - name: Run incremental clang-tidy
+        id: clang-tidy
+        if: ${{matrix.special == 'clang-tidy'}}
+        env:
+          BASE_REF: "${{format('{0}', github.base_ref || 'develop')}}"
+        run: |
+          if [ "${{github.event_name}}" == "schedule" ]; then
+            echo "Full clang-tidy check on scheduled run."
+            ninja -Cbuild -k0
+            exit $?
+          fi
+          BASE=$(git merge-base origin/${BASE_REF} HEAD)
+          ALL_FILES=$(git diff --name-only --diff-filter=ACM "$BASE" HEAD)
+          set +e
+          CC_FILES=$(grep -E '^(src|app|example)/.*\.cc$' - <<< "$ALL_FILES")
+          set -e
+          if [ -z "$CC_FILES" ]; then
+            echo "No files to run clang-tidy on."
+            exit 0
+          fi
+          echo "Running clang-tidy on: $CC_FILES"
+          ${{env.CLANG_TIDY}} -p build $CC_FILES
+          exit $?
       - name: Build all
         id: build
+        if: ${{matrix.special != 'clang-tidy'}}
         working-directory: build
         run: |
-          if [ "${{matrix.special}}" == "clang-tidy" ]; then
-            ninja -k0
-          else
             ninja -v -k0
-          fi
       - name: Regenerate ROOT test data
         if: ${{matrix.geant == '11.0'}}
         working-directory: build

CITATION.cff

@@ -0,0 +1,116 @@
+# Pleace cite the following article when referencing Celeritas in a publication:
+#
+# (Plain text, Chicago author-date 17th ed):
+#   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.
+#
+# (BibLaTeX):
+#    @article{celer-chep-2024,
+#      title = {Celeritas: {{Accelerating Geant4}} with {{GPUs}}},
+#      author = {Johnson, Seth R. and Lund, Amanda and Canal, Philippe and Tognini, Stefano C. and Esseiva, Julien and Jun, Soon Yung and Lima, Guilherme and Biondo, Elliott and Evans, Thomas and Demarteau, Marcel and Romano, Paul},
+#      date = {2024},
+#      journaltitle = {EPJ Web of Conferences},
+#      volume = {295},
+#      pages = {11005},
+#      doi = {10.1051/epjconf/202429511005}
+#    }
+#
+# Note: This information is also present in the README.md and needs to
+# kept in sync.
+#
+# (CFF):
+
+cff-version: 1.2.0
+type: software
+message: "Please cite the following article when referencing Celeritas in a publication."
+title: "Celeritas"
+type: software
+license:
+  - Apache-2.0
+  - MIT
+authors:
+  - family-names: Johnson
+    given-names: Seth R.
+    orcid: "https://orcid.org/0000-0003-1504-8966"
+  - family-names: Lund
+    given-names: Amanda
+    orcid: "https://orcid.org/0000-0002-8316-0709"
+  - family-names: Jun
+    given-names: Soon Yung
+    orcid: "https://orcid.org/0000-0003-3370-6109"
+  - family-names: Tognini
+    given-names: Stefano
+    orcid: "https://orcid.org/0000-0001-9741-6608"
+  - family-names: Lima
+    given-names: Guilherme
+    orcid: "https://orcid.org/0000-0003-4585-0546"
+  - family-names: Canal
+    given-names: Philippe
+    orcid: "https://orcid.org/0000-0002-7748-7887"
+  - family-names: Morgan
+    given-names: Ben
+  - family-names: Evans
+    given-names: Tom
+    orcid: "https://orcid.org/0000-0001-5743-3788"
+  - family-names: Esseiva
+    given-names: Julien
+date-released: 2022
+url: https://doi.org/10.11578/dc.20221011.1
+identifiers:
+  - type: doi
+    value: 10.11578/dc.20221011.1
+keywords:
+  - monte carlo
+  - particle transport
+  - high energy physics
+  - detector simulation
+  - computational physics
+  - hep
+  - cuda
+  - hip
+preferred-citation:
+  authors:
+    - family-names: Johnson
+      given-names: Seth R.
+      orcid: "https://orcid.org/0000-0003-1504-8966"
+    - family-names: Lund
+      given-names: Amanda
+      orcid: "https://orcid.org/0000-0002-8316-0709"
+    - family-names: Canal
+      given-names: Philippe
+      orcid: "https://orcid.org/0000-0002-7748-7887"
+    - family-names: Tognini
+      given-names: Stefano C.
+      orcid: "https://orcid.org/0000-0001-9741-6608"
+    - family-names: Esseiva
+      given-names: Julien
+    - family-names: Jun
+      given-names: Soon Yung
+      orcid: "https://orcid.org/0000-0003-3370-6109"
+    - family-names: Lima
+      given-names: Guilherme
+      orcid: "https://orcid.org/0000-0003-4585-0546"
+    - family-names: Biondo
+      given-names: Elliott
+    - family-names: Evans
+      given-names: Thomas
+      orcid: "https://orcid.org/0000-0001-5743-3788"
+    - family-names: Demarteau
+      given-names: Marcel
+    - family-names: Romano
+      given-names: Paul
+      orcid: "https://orcid.org/0000-0002-1147-045X"
+  title: "Celeritas: Accelerating Geant4 with GPUs"
+  type: article
+  journal: "EPJ Web of Conferences"
+  volume: 295
+  number: 11005
+  issue-title: "26th International Conference on Computing in High Energy and Nuclear Physics (CHEP 2023)"
+  date-published: 2024
+  identifiers:
+    - type: doi
+      value: 10.1051/epjconf/202429511005
+  abstract: >-
+    Celeritas is a new Monte Carlo (MC) detector simulation code designed for computationally intensive applications (specifically, High Luminosity Large Hadron Collider (HL-LHC) simulation) on high-performance heterogeneous architectures. In the past two years Celeritas has advanced from prototyping a GPU-based single physics model in infinite medium to implementing a full set of electromagnetic (EM) physics processes in complex geometries. The current release of Celeritas, version 0.3, has incorporated full device-based navigation, an event loop in the presence of magnetic fields, and detector hit scoring. New functionality incorporates a scheduler to offload electromagnetic physics to the GPU within a Geant4-driven simulation, enabling integration of Celeritas into high energy physics (HEP) experimental frameworks such as CMSSW. On the Summit supercomputer, Celeritas performs EM physics between 6× and 32× faster using the machine’s Nvidia GPUs compared to using only CPUs. When running a multithreaded Geant4 ATLAS test beam application with full hadronic physics, using Celeritas to accelerate the EM physics results in an overall simulation speedup of 1.8–2.3× on GPU and 1.2× on CPU.

CONTRIBUTING.rst

@@ -118,7 +118,7 @@ Congratulations!
 
 .. [resol] When you've fully implemented the reviewer's comment, you may mark
    it as resolved without commenting.  Do not resolve a conversation if you
-   disagree with the feed: instead, post your view in a follow-on comment and
+   disagree with the feedback: instead, post your view in a follow-on comment and
    wait for the reviewer to respond. If you comment, whether to supplement your
    change or to iterate with the reviewer, please do not resolve the
    conversation since that makes it hard to find your comment.

README.md

@@ -25,19 +25,47 @@ doc` (user) or `ninja doxygen` (developer).
 # Installation for applications
 
 The easiest way to install Celeritas as a library/app is with Spack:
-- Follow the first two steps above to install [Spack][spack-start] and set up its CUDA usage.
-- Install Celeritas with `spack install celeritas`
-- Use `spack load celeritas` to add the installation to your `PATH`.
+- Follow these steps to install [Spack][spack-start].
+```console
+# 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)
+```
+- Install Celeritas with
+```console
+spack install celeritas
+```console
+- Add the Celeritas installation to your `PATH` with:
+```console
+spack load celeritas
+```
 
 To 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 the following configuration:
+To do so, set Spack up its CUDA usage:
+```console
+. 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:
+```console
+$ spack install celeritas
+```
+If Celeritas was installed with a different configuration do
+```console
+$ spack install --fresh celeritas
+```
+If you need to set a default configuration
 ```console
-# Replace cuda_arch=80 with your target architecture
-$ spack config add packages:vecgeom:variants:"cxxstd=17 +cuda cuda_arch=80"
 $ spack install celeritas +cuda cuda_arch=80
 ```
 
+
 Then see the "Downstream usage as a library" section of the [installation
 documentation][install] for how to use Celeritas in your application or framework.
 
@@ -62,7 +90,7 @@ $ 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=70"
+$ spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=80"
 $ spack install
 # Configure, build, and test
 $ ./build.sh base
@@ -97,12 +125,11 @@ Geant4:
 
 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 platforms ([Jenkins][jenkins] and [GitHub Actions][gha]).
+The full set of configurations is viewable on CI platform [GitHub Actions][gha]).
 Compatibility fixes that do not cause newer versions to fail are welcome.
 
 [spack]: https://github.com/spack/spack
 [install]: https://celeritas-project.github.io/celeritas/user/main/installation.html
-[jenkins]: https://cloud.cees.ornl.gov/jenkins-ci/job/celeritas/job/develop
 [gha]: https://github.com/celeritas-project/celeritas/actions
 
 # Development
@@ -111,8 +138,8 @@ See the [contribution guide][contributing-guidelines] for the contribution proce
 [the development guidelines][development-guidelines] for further
 details on coding in Celeritas, and [the administration guidelines][administration-guidelines] for community standards and roles.
 
-[contributing-guidelines]: https://celeritas-project.github.io/celeritas/user/appendix/development.html#contributing-to-celeritas
-[development-guidelines]: https://celeritas-project.github.io/celeritas/user/appendix/development.html#code-development-guidelines
+[contributing-guidelines]: https://celeritas-project.github.io/celeritas/user/development/contributing.html
+[development-guidelines]: https://celeritas-project.github.io/celeritas/user/development/coding.html
 [administration-guidelines]: https://celeritas-project.github.io/celeritas/user/appendix/administration.html
 
 # Directory structure
@@ -124,17 +151,22 @@ details on coding in Celeritas, and [the administration guidelines][administrati
 | **doc**       | Code documentation and manual                         |
 | **example**   | Example applications and input files                  |
 | **external**  | Automatically fetched external CMake dependencies     |
-| **interface** | Wrapper interfaces to Celeritas library functions     |
 | **scripts**   | Development and continuous integration helper scripts |
 | **src**       | Library source code                                   |
 | **test**      | Unit tests                                            |
 
 # Citing Celeritas
 
-If using Celeritas in your work, we ask that you cite the code using its
-[DOECode](https://www.osti.gov/doecode/biblio/94866) registration:
+<!-- This section should be kept in sync with the CITATIONS.cff file -->
+
+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](https://www.osti.gov/doecode/biblio/94866) registration:
 
-> Seth R. Johnson, Amanda Lund, Soon Yung Jun, Stefano Tognini, Guilherme Lima, Paul Romano, Philippe Canal, Ben Morgan, and Tom Evans. “Celeritas,” July 2022. https://doi.org/10.11578/dc.20221011.1.
+> 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 available in our [citation file](doc/_static/celeritas.bib).
+core team members is continually updated at [our publications page](https://github.com/celeritas-project/celeritas/blob/doc/gh-pages-base/publications.md)
+and displayed on [the official project web site](https://celeritas.ornl.gov/).