From 95b19ed1749b7db1768d45f35e02cfbf98de82f9 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Mon, 30 Dec 2024 15:56:45 -0500
Subject: [PATCH 01/20] Fix typo to enable 'accel' examples

---
 scripts/ci/test-examples.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/ci/test-examples.sh b/scripts/ci/test-examples.sh
index f6c6c12df0..587ccfda81 100755
--- a/scripts/ci/test-examples.sh
+++ b/scripts/ci/test-examples.sh
@@ -37,7 +37,7 @@ build_local
 ./minimal
 
 
-if [ -z "CELER_DISABLE_ACCEL_EXAMPLES" ]; then
+if [ -z "${CELER_DISABLE_ACCEL_EXAMPLES}" ]; then
   cd "${CELER_SOURCE_DIR}/example/accel"
   build_local
   ctest -V --no-tests=error

From decef60a6a4d26712df383b3f99e2838306beef6 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Mon, 30 Dec 2024 16:00:15 -0500
Subject: [PATCH 02/20] Use debug output for examples

---
 scripts/ci/test-examples.sh | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/ci/test-examples.sh b/scripts/ci/test-examples.sh
index 587ccfda81..73c27c49aa 100755
--- a/scripts/ci/test-examples.sh
+++ b/scripts/ci/test-examples.sh
@@ -32,6 +32,8 @@ build_local() {
   ninja
 }
 
+export CELER_LOG=debug CELER_LOG_LOCAL=debug
+
 cd "${CELER_SOURCE_DIR}/example/minimal"
 build_local
 ./minimal

From a4711d11746d587311f86486ac65ec33b58db10f Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 24 Dec 2024 15:37:07 -0600
Subject: [PATCH 03/20] Fix documentation and use uniform distribution

---
 .../em/distribution/MuAngularDistribution.hh  | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/src/celeritas/em/distribution/MuAngularDistribution.hh b/src/celeritas/em/distribution/MuAngularDistribution.hh
index e0819830b3..e032045d1b 100644
--- a/src/celeritas/em/distribution/MuAngularDistribution.hh
+++ b/src/celeritas/em/distribution/MuAngularDistribution.hh
@@ -12,7 +12,7 @@
 #include "corecel/math/Algorithms.hh"
 #include "celeritas/Constants.hh"
 #include "celeritas/Quantities.hh"
-#include "celeritas/random//distribution/GenerateCanonical.hh"
+#include "celeritas/random/distribution/UniformRealDistribution.hh"
 
 namespace celeritas
 {
@@ -35,8 +35,8 @@ namespace celeritas
    r_{\text{max}} = frac{\pi}{2} E' / m \min(1, E' / \epsilon),
  * \f]
  * and where \f$ m \f$ is the incident muon mass, \f$ E \f$ is incident energy,
- * \$ \epsilon \f$ is the emitted energy, \f$ E' = E - \epsilon \f$, and \f$
- * \xi \sim U(0,1) \f$.
+ * \f$ \epsilon \f$ is the emitted energy,
+ * \f$ E' = E - \epsilon \f$, and \f$ \xi \sim U(0,1) \f$.
  *
  * \note This performs the same sampling routine as in Geant4's \c
  * G4ModifiedMephi class and documented in section 11.2.4 of the Geant4 Physics
@@ -64,7 +64,7 @@ class MuAngularDistribution
     // Incident particle Lorentz factor
     real_type gamma_;
     // r_max^2 / (1 + r_max^2)
-    real_type a_over_xi_;
+    UniformRealDistribution<real_type> sample_a_;
 };
 
 //---------------------------------------------------------------------------//
@@ -80,11 +80,10 @@ MuAngularDistribution::MuAngularDistribution(Energy inc_energy,
     : gamma_(1 + value_as<Energy>(inc_energy) / value_as<Mass>(inc_mass))
 {
     real_type r_max_sq = ipow<2>(
-        gamma_ * constants::pi * real_type(0.5)
-        * min<real_type>(
-            1,
-            gamma_ * value_as<Mass>(inc_mass) / value_as<Energy>(energy) - 1));
-    a_over_xi_ = r_max_sq / (1 + r_max_sq);
+        real_type(0.5) * constants::pi * gamma_
+        * min(real_type(1),
+              gamma_ * value_as<Mass>(inc_mass) / value_as<Energy>(energy) - 1));
+    sample_a_ = {0, r_max_sq / (1 + r_max_sq)};
 }
 
 //---------------------------------------------------------------------------//
@@ -94,7 +93,7 @@ MuAngularDistribution::MuAngularDistribution(Energy inc_energy,
 template<class Engine>
 CELER_FUNCTION real_type MuAngularDistribution::operator()(Engine& rng)
 {
-    real_type a = generate_canonical(rng) * a_over_xi_;
+    real_type a = sample_a_(rng);
     return std::cos(std::sqrt(a / (1 - a)) / gamma_);
 }
 

From 9bd1a784d392fb49eabe970974d762678a8b249c Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 08:09:06 -0500
Subject: [PATCH 04/20] Fix missing error-on-doxygen-warnings on PRs

---
 .github/workflows/doc.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 7974ef8b01..a52e9f32b3 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -37,7 +37,7 @@ jobs:
           cmake \
             -DCELERITAS_BUILD_DOCS=ON \
             -DCELERITAS_DOXYGEN_BUILD_TESTS=ON \
-            ${{ github.workflow == 'pr'
+            ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
              || ''}} \
             -GNinja \

From 24445057c2859666a1a1bf3fa16861a9bc727649 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 08:11:28 -0500
Subject: [PATCH 05/20] Specify celeritas build options for documentation

---
 .github/workflows/doc.yml                   | 13 ++++++-------
 scripts/cmake-presets/ci-ubuntu-github.json | 11 +++++++++++
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index a52e9f32b3..149371f096 100644
--- a/.github/workflows/doc.yml
+++ b/.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-')
@@ -23,7 +24,7 @@ jobs:
         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 gcc
       - name: Check out Celeritas
         uses: actions/checkout@v4
         with:
@@ -34,9 +35,7 @@ jobs:
         # Disable expensive graphs for PRs also
         run: |
           mkdir build && cd build
-          cmake \
-            -DCELERITAS_BUILD_DOCS=ON \
-            -DCELERITAS_DOXYGEN_BUILD_TESTS=ON \
+          cmake --preset=${CMAKE_PRESET} \
             ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
              || ''}} \
@@ -48,7 +47,7 @@ jobs:
           ninja doxygen
           find doc/doxygen-html -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
@@ -93,7 +92,7 @@ jobs:
           ninja doc
           find doc/html -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
diff --git a/scripts/cmake-presets/ci-ubuntu-github.json b/scripts/cmake-presets/ci-ubuntu-github.json
index 7a40df8f80..26cf27fd39 100644
--- a/scripts/cmake-presets/ci-ubuntu-github.json
+++ b/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"],

From 5fa419d16af4bdb7a055e6768da529fd3cfb36c6 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 08:20:54 -0500
Subject: [PATCH 06/20] Add documentation about missing SDs

---
 doc/implementation/geant4-interface.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/implementation/geant4-interface.rst b/doc/implementation/geant4-interface.rst
index 1ea40bf274..a884647b2d 100644
--- a/doc/implementation/geant4-interface.rst
+++ b/doc/implementation/geant4-interface.rst
@@ -45,6 +45,18 @@ 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::
+
+   *** 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 +93,8 @@ Interface utilities
 
 .. doxygenclass:: celeritas::ExceptionConverter
 
+.. doxygenstruct:: celeritas::AlongStepFactoryInput
+
 .. doxygenclass:: celeritas::AlongStepFactoryInterface
 
 

From 32463e629f1c2c42f4685a2bcd6021f4decc0eae Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 08:39:41 -0500
Subject: [PATCH 07/20] Add example SD to tracking manager offload and fix SD
 options for others

---
 example/accel/fastsim-offload.cc         |  4 ++
 example/accel/simple-offload.cc          |  5 ++-
 example/accel/trackingmanager-offload.cc | 57 +++++++++++++++++++++++-
 3 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/example/accel/fastsim-offload.cc b/example/accel/fastsim-offload.cc
index 0469086098..eed6408888 100644
--- a/example/accel/fastsim-offload.cc
+++ b/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
diff --git a/example/accel/simple-offload.cc b/example/accel/simple-offload.cc
index 88c94b73a1..32fdb2e4c9 100644
--- a/example/accel/simple-offload.cc
+++ b/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
diff --git a/example/accel/trackingmanager-offload.cc b/example/accel/trackingmanager-offload.cc
index 3887d42c07..90c1d3c30f 100644
--- a/example/accel/trackingmanager-offload.cc
+++ b/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,6 +101,9 @@ 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
@@ -80,13 +111,24 @@ class DetectorConstruction final : public G4VUserDetectorConstruction
         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";
+        }
+    }
 };
 
 //---------------------------------------------------------------------------//

From c4e9b9e4f225e83d85495bf5e070fc290bb4cb4d Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 08:48:52 -0500
Subject: [PATCH 08/20] Fix cmake presets, use cmake build, fix user doc

---
 .github/workflows/doc.yml | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 149371f096..28932d855f 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -35,16 +35,16 @@ jobs:
         # Disable expensive graphs for PRs also
         run: |
           mkdir build && cd build
-          cmake --preset=${CMAKE_PRESET} \
+          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
+          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
+          cmake --build --preset=base --target doxygen
           find doc/doxygen-html -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         if: ${{env.CELER_UPLOAD_DOC}}
@@ -63,7 +63,7 @@ jobs:
         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 gcc
       - uses: actions/setup-python@v5
         with:
           python-version: '3.10' 
@@ -79,17 +79,16 @@ jobs:
       - name: Configure celeritas
         run: |
           mkdir build && cd build
-          cmake \
-            -DCELERITAS_BUILD_DOCS=ON \
-            -DDOXYGEN_HAVE_DOT="NO" \
-            ${{ github.workflow == 'pr'
+          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
+          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
         run: |
-          ninja doc
+          cmake --build --preset=base --target doc
           find doc/html -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         if: ${{env.CELER_UPLOAD_DOC}}

From 1b29547d50da42ab88a416d1e21324f4eef09e7b Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 10:55:19 -0500
Subject: [PATCH 09/20] Fix presets

---
 .github/workflows/doc.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 28932d855f..3c5bd9214a 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -34,8 +34,8 @@ jobs:
         # Turn warnings into errors only for PRs
         # Disable expensive graphs for PRs also
         run: |
-          mkdir build && cd build
           ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
+          mkdir build && cd build
           cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
             ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
@@ -78,8 +78,8 @@ jobs:
             pip install -r scripts/doc-requirements.txt
       - name: Configure celeritas
         run: |
-          mkdir build && cd build
           ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
+          mkdir build && cd build
           cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
             ${{ github.workflow == 'pull_request'
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DCELERITAS_SPHINX_USER_HTML_ARGS="-W;--keep-going"'

From 22570da14df45f6327a97a47d1787e5393d977d6 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 10:56:55 -0500
Subject: [PATCH 10/20] Update dependencies

---
 .github/workflows/build-ultralite.yml | 2 +-
 .github/workflows/doc.yml             | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build-ultralite.yml b/.github/workflows/build-ultralite.yml
index e598dd2c28..8618191e92 100644
--- a/.github/workflows/build-ultralite.yml
+++ b/.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
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 3c5bd9214a..cd93a83f6f 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -24,7 +24,7 @@ jobs:
         run: |
             sudo apt-get -y update
             sudo apt-get -y install \
-                cmake graphviz ninja-build doxygen nlohmann-json3-dev gcc
+                cmake graphviz ninja-build doxygen nlohmann-json3-dev
       - name: Check out Celeritas
         uses: actions/checkout@v4
         with:
@@ -63,7 +63,7 @@ jobs:
         run: |
             sudo apt-get -y update
             sudo apt-get -y install \
-                cmake graphviz ninja-build doxygen nlohmann-json3-dev gcc
+                cmake graphviz ninja-build doxygen nlohmann-json3-dev
       - uses: actions/setup-python@v5
         with:
           python-version: '3.10' 

From 95f7ff563edaac1e93622687863042446dd95657 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 11:04:01 -0500
Subject: [PATCH 11/20] Fix working dir and use env

---
 .github/workflows/doc.yml | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index cd93a83f6f..5e2e160870 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -18,6 +18,9 @@ env:
 
 jobs:
   dev:
+    env:
+      CELER_TARGET: doxygen
+      CELER_UPLOAD_DIR: build/doc/doxygen-html
     runs-on: ubuntu-latest
     steps:
       - name: Install dependencies
@@ -42,15 +45,14 @@ jobs:
              || ''}} \
             ..
       - name: Build documentation
-        working-directory: build
         run: |
-          cmake --build --preset=base --target doxygen
-          find doc/doxygen-html -name '*.md5' -exec rm {} +
+          cmake --build --preset=base --target ${CELER_TARGET}
+          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         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
@@ -58,6 +60,9 @@ jobs:
 
   user:
     runs-on: ubuntu-latest
+    env:
+      CELER_TARGET: doc
+      CELER_UPLOAD_DIR: build/doc/html
     steps:
       - name: Install dependencies
         run: |
@@ -85,16 +90,15 @@ jobs:
              && '-DDOXYGEN_WARN_AS_ERROR="YES" -DCELERITAS_SPHINX_USER_HTML_ARGS="-W;--keep-going"'
              || ''}} \
             ..
-      - name: Build user documentation
-        working-directory: build
+      - name: Build documentation
         run: |
-          cmake --build --preset=base --target doc
-          find doc/html -name '*.md5' -exec rm {} +
+          cmake --build --preset=base --target ${CELER_TARGET}
+          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         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

From e0874883606235a3fb799aa2883d8f74b97604c5 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 11:23:09 -0500
Subject: [PATCH 12/20] Fix build presets

---
 .github/workflows/doc.yml                   |  4 ++--
 scripts/cmake-presets/ci-ubuntu-github.json | 12 ++++++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 5e2e160870..b978090db0 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -46,7 +46,7 @@ jobs:
             ..
       - name: Build documentation
         run: |
-          cmake --build --preset=base --target ${CELER_TARGET}
+          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
           find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         if: ${{env.CELER_UPLOAD_DOC}}
@@ -92,7 +92,7 @@ jobs:
             ..
       - name: Build documentation
         run: |
-          cmake --build --preset=base --target ${CELER_TARGET}
+          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
           find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
       - name: Upload artifacts
         if: ${{env.CELER_UPLOAD_DOC}}
diff --git a/scripts/cmake-presets/ci-ubuntu-github.json b/scripts/cmake-presets/ci-ubuntu-github.json
index 26cf27fd39..b11dfbccaf 100644
--- a/scripts/cmake-presets/ci-ubuntu-github.json
+++ b/scripts/cmake-presets/ci-ubuntu-github.json
@@ -168,6 +168,18 @@
       }
     }
   ],
+  "buildPresets": [
+    {
+      "name": "base",
+      "configurePreset": "base",
+      "nativeToolOptions": ["-k0"],
+      "verbose": true
+    },
+    {
+      "name": "doc",
+      "inherits": "base"
+    }
+  ],
   "testPresets": [
     {
       "name": "base",

From 2679960e3be07b676809a3255252c7e2abd22bbe Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 12:34:21 -0500
Subject: [PATCH 13/20] Add/improve docs for wentzel scattering

---
 src/celeritas/em/data/CommonCoulombData.hh    |  5 +++-
 .../em/distribution/WentzelDistribution.hh    | 15 ++++++-----
 src/celeritas/em/xs/NuclearFormFactors.hh     |  2 +-
 src/celeritas/em/xs/WentzelHelper.hh          | 25 +++++++++++++------
 4 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/src/celeritas/em/data/CommonCoulombData.hh b/src/celeritas/em/data/CommonCoulombData.hh
index e8ae40612f..275ee0aed4 100644
--- a/src/celeritas/em/data/CommonCoulombData.hh
+++ b/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
 {
diff --git a/src/celeritas/em/distribution/WentzelDistribution.hh b/src/celeritas/em/distribution/WentzelDistribution.hh
index f0bca16ed9..55d55e972f 100644
--- a/src/celeritas/em/distribution/WentzelDistribution.hh
+++ b/src/celeritas/em/distribution/WentzelDistribution.hh
@@ -25,9 +25,7 @@ namespace celeritas
 {
 //---------------------------------------------------------------------------//
 /*!
- * Helper class for \c CoulombScatteringInteractor .
- *
- * Samples the polar scattering angle for the Wentzel Coulomb scattering model.
+ * Sample the polar scattering angle cosine for Wentzel Coulomb scattering.
  *
  * This chooses between sampling scattering off an electron or nucleus based on
  * the relative cross sections. Electron scattering angle imposes a maximum
@@ -37,12 +35,17 @@ namespace celeritas
  * nuclear cross sections (calculated by \c WentzelHelper) and nuclear form
  * factors (see \c ExpNuclearFormFactor, \c GaussianNuclearFormFactor, and \c
  * UUNuclearFormFactor ) that describe an approximate spatial charge
- * distribution of the nucleus.
+ * distribution of the nucleus. The class is used by \c
+ * CoulombScatteringInteractor .
  *
  * The polar angle distribution is given in [Fern] eqn 88 and is normalized on
  the interval
  * \f$ cos\theta \in [\cos\theta_\mathrm{min}, \cos\theta_\mathrm{max}] \f$.
- * The sampling function for \f$ \mu = \frac{1}{2}(1 - \cos\theta) \f$ is
+ * The sampling function for the angular deflection
+ * \f[
+ * \mu(\theta) \equiv \frac{1}{2}(1 - \cos\theta)
+ * \f]
+ * is
  * \f[
    \mu = \mu_1 + \frac{(A + \mu_1) \xi (\mu_2 - \mu_1)}{A + \mu_2 - \xi (\mu_2
    - \mu_1)},
@@ -173,7 +176,7 @@ WentzelDistribution::WentzelDistribution(
 
 //---------------------------------------------------------------------------//
 /*!
- * Sample the polar scattered angle of the incident particle.
+ * Sample the cosine polar scattered angle of the incident particle.
  */
 template<class Engine>
 CELER_FUNCTION real_type WentzelDistribution::operator()(Engine& rng) const
diff --git a/src/celeritas/em/xs/NuclearFormFactors.hh b/src/celeritas/em/xs/NuclearFormFactors.hh
index c92079bd07..0a0ade2a1e 100644
--- a/src/celeritas/em/xs/NuclearFormFactors.hh
+++ b/src/celeritas/em/xs/NuclearFormFactors.hh
@@ -151,7 +151,7 @@ class GaussianNuclearFormFactor : public ExpNuclearFormFactor
  * [FMS93] J.M. Fernández-Varea, R. Mayol, F. Salvat, Cross sections for
  *       elastic scattering of fast electrons and positrons by atoms, Nuclear
  *       Instruments and Methods in Physics Research Section B: Beam
- * Interactions with Materials and Atoms 82 (1993) 39–45.
+ *       Interactions with Materials and Atoms 82 (1993) 39–45.
  *       https://doi.org/10.1016/0168-583X(93)95079-K.
  */
 class UUNuclearFormFactor : public NuclearFormFactorTraits
diff --git a/src/celeritas/em/xs/WentzelHelper.hh b/src/celeritas/em/xs/WentzelHelper.hh
index 7b1c54895b..9e17989f68 100644
--- a/src/celeritas/em/xs/WentzelHelper.hh
+++ b/src/celeritas/em/xs/WentzelHelper.hh
@@ -59,7 +59,7 @@ class WentzelHelper
         return screening_coefficient_;
     }
 
-    //! Get the Mott factor
+    //! Get the Mott factor (maximum, used for rejection)
     CELER_FUNCTION real_type mott_factor() const { return mott_factor_; }
 
     //! Get the multiplicative factor for the cross section
@@ -102,7 +102,7 @@ class WentzelHelper
     calc_screening_coefficient(ParticleTrackView const& particle) const;
 
     // Calculate the screening coefficient R^2 for electrons
-    CELER_CONSTEXPR_FUNCTION real_type screen_r_sq_elec() const;
+    static CELER_CONSTEXPR_FUNCTION MomentumSq screen_r_sq_elec();
 
     // Calculate the multiplicative factor for the cross section
     inline CELER_FUNCTION real_type
@@ -195,6 +195,13 @@ CELER_FUNCTION real_type WentzelHelper::calc_xs_factor(
 /*!
  * Calculate the Moliere screening coefficient as in [PRM] eqn 8.51.
  *
+ * See Eq.32 in [Fern], referencing Bethe's re-derivation of Moliere
+ * scattering:
+ *  Bethe, H. A. “Moliere’s Theory of Multiple Scattering.” Physical Review
+ *  89, no. 6 (March 15, 1953): 1256–66.
+ * https://doi.org/10.1103/PhysRev.89.1256.
+ *
+ *
  * \note The \c screenZ in Geant4 is equal to twice the screening coefficient.
  */
 CELER_FUNCTION real_type WentzelHelper::calc_screening_coefficient(
@@ -205,9 +212,11 @@ CELER_FUNCTION real_type WentzelHelper::calc_screening_coefficient(
     real_type sq_cbrt_z = fastpow(real_type(target_z_.get()), real_type{2} / 3);
     if (target_z_.get() > 1)
     {
+        // TODO: tau correction factor and "min" value are of unknown
+        // provenance. The equation in Fernandez 1993 has factor=1, no special
+        // casing for z=1, and no "min" for the correction
         real_type tau = value_as<Energy>(particle.energy())
                         / value_as<Mass>(particle.mass());
-        // TODO: Reference for this factor?
         real_type factor = std::sqrt(tau / (tau + sq_cbrt_z));
 
         correction = min(target_z_.get() * real_type{1.13},
@@ -218,7 +227,8 @@ CELER_FUNCTION real_type WentzelHelper::calc_screening_coefficient(
                                    * factor / particle.beta_sq());
     }
 
-    return correction * this->screen_r_sq_elec() * sq_cbrt_z
+    return correction * sq_cbrt_z
+           * value_as<MomentumSq>(this->screen_r_sq_elec())
            / value_as<MomentumSq>(particle.momentum_sq());
 }
 
@@ -237,14 +247,13 @@ CELER_FUNCTION real_type WentzelHelper::calc_screening_coefficient(
    C_{TF} = \frac{1}{2} \left(\frac{3\pi}{4}\right)^{2/3}.
  * \f]
  */
-CELER_CONSTEXPR_FUNCTION real_type WentzelHelper::screen_r_sq_elec() const
+CELER_CONSTEXPR_FUNCTION auto WentzelHelper::screen_r_sq_elec() -> MomentumSq
 {
     //! Thomas-Fermi constant \f$ C_{TF} \f$
-    constexpr real_type ctf = 0.8853413770001135;
+    constexpr Constant ctf{0.8853413770001135};
 
     return native_value_to<MomentumSq>(
-               ipow<2>(constants::hbar_planck / (2 * ctf * constants::a0_bohr)))
-        .value();
+        ipow<2>(constants::hbar_planck / (2 * ctf * constants::a0_bohr)));
 }
 
 //---------------------------------------------------------------------------//

From f6d90d65b15dfe384a9371fcc556a85733db7139 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 12:45:10 -0500
Subject: [PATCH 14/20] Fix doxygen build issues

---
 src/celeritas/random/RngReseed.hh          | 2 +-
 test/celeritas/global/AlongStepTestBase.hh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/celeritas/random/RngReseed.hh b/src/celeritas/random/RngReseed.hh
index 8a4e12f5cb..c2b11a0b1e 100644
--- a/src/celeritas/random/RngReseed.hh
+++ b/src/celeritas/random/RngReseed.hh
@@ -28,7 +28,7 @@ void reseed_rng(HostCRef<RngParamsData> const&,
                 StreamId,
                 UniqueEventId);
 
-#if !CELER_USE_DEVICE
+#if !CELER_USE_DEVICE && (!defined(__DOXYGEN__) || __DOXYGEN__ > 0x010908)
 //---------------------------------------------------------------------------//
 /*!
  * Reinitialize the RNG states on device at the start of an event.
diff --git a/test/celeritas/global/AlongStepTestBase.hh b/test/celeritas/global/AlongStepTestBase.hh
index 9ac7faa55a..bdd0b74b34 100644
--- a/test/celeritas/global/AlongStepTestBase.hh
+++ b/test/celeritas/global/AlongStepTestBase.hh
@@ -3,7 +3,7 @@
 // See the top-level COPYRIGHT file for details.
 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
 //---------------------------------------------------------------------------//
-//! \file celeritas/alongstepTestBase.hh
+//! \file celeritas/AlongStepTestBase.hh
 //---------------------------------------------------------------------------//
 #pragma once
 

From 8abaf72efdc98d94122edb4aaf75e9a27c372bba Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 13:10:40 -0500
Subject: [PATCH 15/20] fixup! Fix doxygen build issues

---
 doc/implementation/geant4-interface.rst    | 4 +++-
 test/celeritas/global/AlongStepTestBase.hh | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/implementation/geant4-interface.rst b/doc/implementation/geant4-interface.rst
index a884647b2d..cc446d394e 100644
--- a/doc/implementation/geant4-interface.rst
+++ b/doc/implementation/geant4-interface.rst
@@ -49,7 +49,9 @@ 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::
+compatible with Celeritas), the Celeritas setup will fail with an error like:
+
+.. code-block:: none
 
    *** G4Exception : celer0001
          issued by : accel/detail/HitManager.cc:210
diff --git a/test/celeritas/global/AlongStepTestBase.hh b/test/celeritas/global/AlongStepTestBase.hh
index bdd0b74b34..e592583b2e 100644
--- a/test/celeritas/global/AlongStepTestBase.hh
+++ b/test/celeritas/global/AlongStepTestBase.hh
@@ -3,7 +3,7 @@
 // See the top-level COPYRIGHT file for details.
 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
 //---------------------------------------------------------------------------//
-//! \file celeritas/AlongStepTestBase.hh
+//! \file celeritas/global/AlongStepTestBase.hh
 //---------------------------------------------------------------------------//
 #pragma once
 

From 5cceb2f210ff13eab007ac2b7c1d67390538867f Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Tue, 31 Dec 2024 15:21:52 -0500
Subject: [PATCH 16/20] Fix cuda build

---
 src/celeritas/random/RngReseed.cu | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/celeritas/random/RngReseed.cu b/src/celeritas/random/RngReseed.cu
index 288cf4df07..4b13f72ff5 100644
--- a/src/celeritas/random/RngReseed.cu
+++ b/src/celeritas/random/RngReseed.cu
@@ -14,6 +14,7 @@
 
 namespace celeritas
 {
+#if !defined(__DOXYGEN__) || __DOXYGEN__ > 0x010908
 //---------------------------------------------------------------------------//
 // KERNEL INTERFACE
 //---------------------------------------------------------------------------//
@@ -36,4 +37,5 @@ void reseed_rng(DeviceCRef<RngParamsData> const& params,
 }
 
 //---------------------------------------------------------------------------//
+#endif
 }  // namespace celeritas

From d53904379f5afc1fc2a1bb2c3e7448f3bb113733 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Wed, 1 Jan 2025 09:45:07 -0500
Subject: [PATCH 17/20] Fix build-from-install test

---
 .github/workflows/build-spack.yml | 7 +++++--
 scripts/ci/test-examples.sh       | 3 ++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build-spack.yml b/.github/workflows/build-spack.yml
index 1035083d59..d11883fa76 100644
--- a/.github/workflows/build-spack.yml
+++ b/.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: |
@@ -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,12 @@ 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.geant
               ) && '1' || ''
             }}
         if: >-
diff --git a/scripts/ci/test-examples.sh b/scripts/ci/test-examples.sh
index 73c27c49aa..450cbad250 100755
--- a/scripts/ci/test-examples.sh
+++ b/scripts/ci/test-examples.sh
@@ -34,11 +34,12 @@ build_local() {
 
 export CELER_LOG=debug CELER_LOG_LOCAL=debug
 
+# Run minimal example
 cd "${CELER_SOURCE_DIR}/example/minimal"
 build_local
 ./minimal
 
-
+# Run Geant4 app example(s)
 if [ -z "${CELER_DISABLE_ACCEL_EXAMPLES}" ]; then
   cd "${CELER_SOURCE_DIR}/example/accel"
   build_local

From 6c2f1e702add6ea0e1fc18e8b96e1deb857b6f17 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Wed, 1 Jan 2025 12:38:42 -0500
Subject: [PATCH 18/20] Don't check examples because geant4 practices are awful

---
 .clang-tidy | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.clang-tidy b/.clang-tidy
index c1c5f1b64a..1e317982ae 100644
--- a/.clang-tidy
+++ b/.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
 ...

From 6af8e04d51d9c828f6702f9433d0d06c368f7f0a Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Wed, 1 Jan 2025 12:40:19 -0500
Subject: [PATCH 19/20] Disable examples with geant4 nav because accel doesn't
 support it

---
 .github/workflows/build-spack.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/build-spack.yml b/.github/workflows/build-spack.yml
index d11883fa76..df6fc2d11a 100644
--- a/.github/workflows/build-spack.yml
+++ b/.github/workflows/build-spack.yml
@@ -235,6 +235,7 @@ jobs:
             ${{
               (   (matrix.special == 'minimal')
                || (matrix.special == 'float')
+               || (matrix.geometry == 'geant4')
                || !matrix.geant
               ) && '1' || ''
             }}

From acdc79ba9c32c1ca0eed20fb33309714282764a6 Mon Sep 17 00:00:00 2001
From: Seth R Johnson <johnsonsr@ornl.gov>
Date: Wed, 1 Jan 2025 13:36:05 -0500
Subject: [PATCH 20/20] fixup! Disable examples with geant4 nav because accel
 doesn't support it

---
 .github/workflows/build-spack.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build-spack.yml b/.github/workflows/build-spack.yml
index df6fc2d11a..b274cb6799 100644
--- a/.github/workflows/build-spack.yml
+++ b/.github/workflows/build-spack.yml
@@ -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."