Fix accel examples and related CI issues (#1557)

* Fix typo to enable 'accel' examples
* Use debug output for examples
* Fix documentation and use uniform distribution
* Fix missing error-on-doxygen-warnings on PRs
* Specify celeritas build options for documentation
* Add documentation about missing SDs
* Add example SD to tracking manager offload and fix SD options for others
* Fix cmake presets, use cmake build, fix user doc
* Add/improve docs for wentzel scattering
* Fix doxygen build issues
* Fix build-from-install test
* Don't check examples because geant4 practices are awful
* Disable examples with geant4 nav because accel doesn't support it

.clang-tidy

@@ -48,6 +48,6 @@ CheckOptions:
   performance-move-const-arg.CheckTriviallyCopyableMove: false
   performance-move-const-arg.CheckMoveToConstRef: false
 
-HeaderFilterRegex: '(example|app|src/(accel|celeritas|corecel|orange|geocel))/.*\.hh$'
+HeaderFilterRegex: '(app|src/(accel|celeritas|corecel|orange|geocel))/.*\.hh$'
 FormatStyle: file
 ...

.github/workflows/build-spack.yml

@@ -70,7 +70,7 @@ jobs:
         with:
           ref: ${{env.SPACK_REF}}
           buildcache: true
-          color: true  
+          color: true
           path: spack-src
       - name: Initialize spack environment
         run: |
@@ -149,7 +149,7 @@ jobs:
           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")
+          CC_FILES=$(grep -E '^(src|app)/.*\.cc$' - <<< "$ALL_FILES")
           set -e
           if [ -z "$CC_FILES" ]; then
             echo "No files to run clang-tidy on."
@@ -208,6 +208,8 @@ jobs:
             (matrix.special != 'asanlite')
             && (matrix.special != 'clang-tidy')
           }}
+        env:
+          CELER_DISABLE_ACCEL_EXAMPLES: 1 # Only run minimal example
         run: |
           . ${SPACK_VIEW}/rc
           CELER_INSTALL_DIR=${PWD}/build ./scripts/ci/test-examples.sh
@@ -228,11 +230,13 @@ jobs:
           ./bin/celer-sim --version
       - name: Build examples
         # TODO: ASAN requires flags downstream
-        env: 
+        env:
           CELER_DISABLE_ACCEL_EXAMPLES: >-
             ${{
               (   (matrix.special == 'minimal')
                || (matrix.special == 'float')
+               || (matrix.geometry == 'geant4')
+               || !matrix.geant
               ) && '1' || ''
             }}
         if: >-

.github/workflows/build-ultralite.yml

@@ -21,7 +21,7 @@ jobs:
         run: |
           sudo apt-get -q -y update
           sudo apt-get -q -y install \
-            ccache cmake ninja-build
+            ccache cmake ninja-build nlohmann-json3-dev
       - name: Check out Celeritas
         uses: actions/checkout@v4
       - name: Cache ccache

.github/workflows/doc.yml

@@ -8,7 +8,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  celer_upload_doc:  >-
+  CMAKE_PRESET: doc
+  CELER_UPLOAD_DOC:  >-
     ${{  github.ref_name == 'develop'
       || contains(github.ref_name, 'backports/')
       || contains(github.head_ref, 'release-')
@@ -17,13 +18,16 @@ env:
 
 jobs:
   dev:
+    env:
+      CELER_TARGET: doxygen
+      CELER_UPLOAD_DIR: build/doc/doxygen-html
     runs-on: ubuntu-latest
     steps:
       - name: Install dependencies
         run: |
             sudo apt-get -y update
             sudo apt-get -y install \
-                cmake graphviz ninja-build doxygen gcc
+                cmake graphviz ninja-build doxygen nlohmann-json3-dev
       - name: Check out Celeritas
         uses: actions/checkout@v4
         with:
@@ -33,38 +37,38 @@ jobs:
         # Turn warnings into errors only for PRs
         # Disable expensive graphs for PRs also
         run: |
+          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
           mkdir build && cd build
-          cmake \
-            -DCELERITAS_BUILD_DOCS=ON \
-            -DCELERITAS_DOXYGEN_BUILD_TESTS=ON \
-            ${{ github.workflow == 'pr'
+          cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
+            ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
              || ''}} \
-            -GNinja \
             ..
       - name: Build documentation
-        working-directory: build
         run: |
-          ninja doxygen
-          find doc/doxygen-html -name '*.md5' -exec rm {} +
+          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
+          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
-        if: ${{env.celer_upload_doc}}
+        if: ${{env.CELER_UPLOAD_DOC}}
         uses: actions/upload-artifact@v4
         with:
-          path: build/doc/doxygen-html
+          path: ${{env.CELER_UPLOAD_DIR}}
           name: doc-dev
           if-no-files-found: error
           overwrite: true
           retention-days: 1 # developer docs can be large
 
   user:
     runs-on: ubuntu-latest
+    env:
+      CELER_TARGET: doc
+      CELER_UPLOAD_DIR: build/doc/html
     steps:
       - name: Install dependencies
         run: |
             sudo apt-get -y update
             sudo apt-get -y install \
-                cmake graphviz ninja-build doxygen gcc
+                cmake graphviz ninja-build doxygen nlohmann-json3-dev
       - uses: actions/setup-python@v5
         with:
           python-version: '3.10' 
@@ -79,24 +83,22 @@ jobs:
             pip install -r scripts/doc-requirements.txt
       - name: Configure celeritas
         run: |
+          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
           mkdir build && cd build
-          cmake \
-            -DCELERITAS_BUILD_DOCS=ON \
-            -DDOXYGEN_HAVE_DOT="NO" \
-            ${{ github.workflow == 'pr'
+          cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
+            ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DCELERITAS_SPHINX_USER_HTML_ARGS="-W;--keep-going"'
              || ''}} \
-            -GNinja ..
-      - name: Build user documentation
-        working-directory: build
+            ..
+      - name: Build documentation
         run: |
-          ninja doc
-          find doc/html -name '*.md5' -exec rm {} +
+          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
+          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
-        if: ${{env.celer_upload_doc}}
+        if: ${{env.CELER_UPLOAD_DOC}}
         uses: actions/upload-artifact@v4
         with:
-          path: build/doc/html
+          path: ${{env.CELER_UPLOAD_DIR}}
           name: doc-user
           if-no-files-found: error
           overwrite: true

doc/implementation/geant4-interface.rst

@@ -45,6 +45,20 @@ Celeritas. They are also necessary to set up the GPU offloading
 characteristics. Future versions of Celeritas will automate more of these
 settings.
 
+By default, sensitive detectors are automatically mapped from Geant4 to
+Celeritas using the ``enabled`` option of
+:cpp:struct:`celeritas::SDSetupOptions`. If no SDs are present (e.g., in a test
+problem, or one which has only a "stepping manager" which is not presently
+compatible with Celeritas), the Celeritas setup will fail with an error like:
+
+.. code-block:: none
+
+   *** G4Exception : celer0001
+         issued by : accel/detail/HitManager.cc:210
+   Celeritas runtime error: no G4 sensitive detectors are defined: set `SetupOptions.sd.enabled` to `false` if this is expected
+   *** Fatal Exception *** core dump ***
+
+
 .. doxygenstruct:: celeritas::SetupOptions
    :members:
    :no-link:
@@ -81,6 +95,8 @@ Interface utilities
 
 .. doxygenclass:: celeritas::ExceptionConverter
 
+.. doxygenstruct:: celeritas::AlongStepFactoryInput
+
 .. doxygenclass:: celeritas::AlongStepFactoryInterface
 
 

example/accel/fastsim-offload.cc

@@ -73,6 +73,10 @@ class DetectorConstruction final : public G4VUserDetectorConstruction
               "Aluminium", 13., 26.98 * g / mole, 2.700 * g / cm3}}
     {
         setup_options.make_along_step = celeritas::UniformAlongStepFactory();
+
+        // NOTE: since no SD is enabled, we must manually disable Celeritas hit
+        // processing
+        setup_options.sd.enabled = false;
     }
 
     G4VPhysicalVolume* Construct() final

example/accel/simple-offload.cc

@@ -69,7 +69,10 @@ class DetectorConstruction final : public G4VUserDetectorConstruction
               "Aluminium", 13., 26.98 * g / mole, 2.700 * g / cm3}}
     {
         setup_options.make_along_step = celeritas::UniformAlongStepFactory();
-        setup_options.geometry_output_file = "simple-example.gdml";
+
+        // NOTE: since no SD is enabled, we must manually disable Celeritas hit
+        // processing
+        setup_options.sd.enabled = false;
     }
 
     G4VPhysicalVolume* Construct() final

example/accel/trackingmanager-offload.cc

@@ -23,6 +23,7 @@
 #include <G4Positron.hh>
 #include <G4Region.hh>
 #include <G4RegionStore.hh>
+#include <G4SDManager.hh>
 #include <G4SystemOfUnits.hh>
 #include <G4Threading.hh>
 #include <G4ThreeVector.hh>
@@ -48,6 +49,7 @@
 #include <accel/SharedParams.hh>
 #include <accel/SimpleOffload.hh>
 #include <accel/TrackingManagerOffload.hh>
+#include <corecel/Assert.hh>
 #include <corecel/Macros.hh>
 #include <corecel/io/Logger.hh>
 
@@ -64,6 +66,32 @@ G4ThreadLocal celeritas::LocalTransporter local_transporter;
 // Simple interface to running celeritas
 G4ThreadLocal celeritas::SimpleOffload simple_offload;
 
+class SensitiveDetector final : public G4VSensitiveDetector
+{
+  public:
+    explicit SensitiveDetector(std::string name)
+        : G4VSensitiveDetector{std::move(name)}
+    {
+    }
+
+    double edep() const { return edep_; }
+
+  protected:
+    void Initialize(G4HCofThisEvent*) final { edep_ = 0; }
+    bool ProcessHits(G4Step* step, G4TouchableHistory*) final
+    {
+        CELER_ASSERT(step);
+        edep_ += step->GetTotalEnergyDeposit();
+        return true;
+    }
+
+  private:
+    double edep_{0};
+};
+
+// Simple (not best practice) way of accessing SD
+G4ThreadLocal SensitiveDetector const* global_sd{nullptr};
+
 //---------------------------------------------------------------------------//
 class DetectorConstruction final : public G4VUserDetectorConstruction
 {
@@ -73,20 +101,34 @@ class DetectorConstruction final : public G4VUserDetectorConstruction
               "Aluminium", 13., 26.98 * g / mole, 2.700 * g / cm3}}
     {
         setup_options.make_along_step = celeritas::UniformAlongStepFactory();
+
+        // Export a GDML file with the problem setup and SDs
+        setup_options.geometry_output_file = "simple-example.gdml";
     }
 
     G4VPhysicalVolume* Construct() final
     {
         CELER_LOG_LOCAL(status) << "Setting up detector";
         auto* box = new G4Box("world", 1000 * cm, 1000 * cm, 1000 * cm);
         auto* lv = new G4LogicalVolume(box, aluminum_, "world");
+        world_lv_ = lv;
         auto* pv = new G4PVPlacement(
             0, G4ThreeVector{}, lv, "world", nullptr, false, 0);
         return pv;
     }
 
+    void ConstructSDandField() final
+    {
+        auto* sd_manager = G4SDManager::GetSDMpointer();
+        auto detector = std::make_unique<SensitiveDetector>("example-sd");
+        world_lv_->SetSensitiveDetector(detector.get());
+        global_sd = detector.get();
+        sd_manager->AddNewDetector(detector.release());
+    }
+
   private:
-    G4Material* aluminum_;
+    G4Material* aluminum_{nullptr};
+    G4LogicalVolume* world_lv_{nullptr};
 };
 
 //---------------------------------------------------------------------------//
@@ -156,6 +198,19 @@ class EventAction final : public G4UserEventAction
     {
         simple_offload.BeginOfEventAction(event);
     }
+    void EndOfEventAction(G4Event const* event) final
+    {
+        // Log total energy deposition
+        if (global_sd)
+        {
+            CELER_LOG(info) << "Total energy deposited: "
+                            << (global_sd->edep() / CLHEP::MeV) << " MeV";
+        }
+        else
+        {
+            CELER_LOG(error) << "Global SD was not set";
+        }
+    }
 };
 
 //---------------------------------------------------------------------------//

scripts/ci/test-examples.sh

@@ -32,12 +32,15 @@ build_local() {
   ninja
 }
 
+export CELER_LOG=debug CELER_LOG_LOCAL=debug
+
+# Run minimal example
 cd "${CELER_SOURCE_DIR}/example/minimal"
 build_local
 ./minimal
 
-
-if [ -z "CELER_DISABLE_ACCEL_EXAMPLES" ]; then
+# Run Geant4 app example(s)
+if [ -z "${CELER_DISABLE_ACCEL_EXAMPLES}" ]; then
   cd "${CELER_SOURCE_DIR}/example/accel"
   build_local
   ctest -V --no-tests=error

scripts/cmake-presets/ci-ubuntu-github.json

@@ -34,6 +34,17 @@
         "CMAKE_INSTALL_PREFIX": "${sourceDir}/install"
       }
     },
+    {
+      "name": "doc",
+      "inherits": ["base"],
+      "displayName": "Build only documentation",
+      "cacheVariables": {
+        "CELERITAS_BUILD_DOCS":  {"type": "BOOL", "value": "ON"},
+        "CELERITAS_DEBUG":       {"type": "BOOL", "value": "OFF"},
+        "CELERITAS_DOXYGEN_BUILD_TESTS":  {"type": "BOOL", "value": "ON"},
+        "CELERITAS_USE_PNG":     {"type": "BOOL", "value": "OFF"}
+      }
+    },
     {
       "name": "spack",
       "inherits": ["base"],
@@ -157,6 +168,18 @@
       }
     }
   ],
+  "buildPresets": [
+    {
+      "name": "base",
+      "configurePreset": "base",
+      "nativeToolOptions": ["-k0"],
+      "verbose": true
+    },
+    {
+      "name": "doc",
+      "inherits": "base"
+    }
+  ],
   "testPresets": [
     {
       "name": "base",

src/celeritas/em/data/CommonCoulombData.hh

@@ -17,7 +17,10 @@ namespace celeritas
 /*!
  * Physics IDs for MSC.
  *
- * TODO these will probably be changed to a map over all particle IDs.
+ * \todo If we want to extend this *generally*, we should have an array (length
+ * \c ParticleParams::size() ) that maps IDs to "model parameters". For
+ * example, electrons and positrons probably map to the same ID. Light ions and
+ * protons probably do as well.
  */
 struct CoulombIds
 {