Simplify Geant4 user application interface (#1729)

* Remove build/buildformaster in simple integration
* Clean includes
* Add CeleritasG4 header and Celeritas::G4 target
* Update doc
* Use an alias instead of an interface library

Author: sethrj

Diff for: .github/workflows/build-spack.yml

@@ -307,7 +307,7 @@ jobs:
             && matrix.special != 'clang-tidy'
           }}
         env:
-          CELER_DISABLE_ACCEL_EXAMPLES: 1 # Only run minimal example
+          CELER_DISABLE_G4_EXAMPLES: 1 # Only run minimal example
         run: |
           . ${SPACK_VIEW}/rc
           CELER_INSTALL_DIR=${PWD}/build ./scripts/ci/test-examples.sh
@@ -337,7 +337,7 @@ jobs:
           ./bin/celer-sim --config
       - name: Build examples
         env:
-          CELER_DISABLE_ACCEL_EXAMPLES: >-
+          CELER_DISABLE_G4_EXAMPLES: >-
             ${{(
               matrix.special == 'float'
               || !matrix.geant

Diff for: README.md

@@ -87,43 +87,30 @@ library calls to support VecGeom's use of CUDA RDC:
      ${Geant4_LIBRARIES}
 ```
 
-A few includes expose Celeritas classes to the user code:
+One catch-all include exposes the Celeritas high-level offload classes to user
+code:
 ```diff
---- example/accel/trackingmanager-offload.cc
-+++ example/accel/trackingmanager-offload.cc
-@@ -36,2 +36,10 @@
+--- example/geant4/trackingmanager-offload.cc
++++ example/geant4/trackingmanager-offload.cc
+@@ -31,2 +31,4 @@
 
 +// Celeritas
-+#include <accel/AlongStepFactory.hh>
-+#include <accel/SetupOptions.hh>
-+#include <accel/TrackingManagerConstructor.hh>
-+#include <accel/TrackingManagerIntegration.hh>
-+
-+using TMI = celeritas::TrackingManagerIntegration;
-+
- namespace
++#include <CeleritasG4.hh>
+
 ```
 
-Celeritas uses the build/run actions to set up and tear down cleanly:
+Celeritas uses the run action to set up and tear down cleanly:
 ```diff
 --- example/accel/trackingmanager-offload.cc
 +++ example/accel/trackingmanager-offload.cc
-@@ -134,2 +142,3 @@ class RunAction final : public G4UserRunAction
-     void BeginOfRunAction(G4Run const* run) final {
+@@ -133,2 +138,3 @@ class RunAction final : public G4UserRunAction
+     {
 +        TMI::Instance().BeginOfRunAction(run);
      }
-@@ -137,2 +146,3 @@ class RunAction final : public G4UserRunAction
-     void EndOfRunAction(G4Run const* run) final {
+@@ -136,2 +142,3 @@ class RunAction final : public G4UserRunAction
+     {
 +        TMI::Instance().EndOfRunAction(run);
      }
-@@ -179,2 +189,3 @@ class ActionInitialization final : public G4VUserActionInitialization
-      void BuildForMaster() const final {
-+        TMI::Instance().BuildForMaster();
-     }
-@@ -185,2 +197,3 @@ class ActionInitialization final : public G4VUserActionInitialization
-     void Build() const final{
-+        TMI::Instance().Build();
-     }
 ```
 
 And integrates into the tracking loop primarily using the `G4TrackingManager`
@@ -141,6 +128,9 @@ interface:
 +        new celeritas::TrackingManagerConstructor(&tmi));
 ```
 
+More flexible alternatives to this high level interface, compatible with other
+run manager implementations and older versions of Geant4, are described in the
+manual.
 
 [integration]: https://celeritas-project.github.io/celeritas/user/usage/integration.html
 

Diff for: cmake/CeleritasConfig.cmake.in

@@ -178,6 +178,13 @@ if(NOT TARGET celeritas)
 
   # Load targets created by `install(EXPORT celeritas-targets`
   include("${CELERITAS_CMAKE_DIR}/CeleritasTargets.cmake")
+
+  # Add simple alias for user apps
+  if(CELERITAS_USE_Geant4)
+    add_library(Celeritas::G4 ALIAS Celeritas::accel)
+  else()
+    add_library(Celeritas::G4 ALIAS Celeritas::BuildFlags)
+  endif()
 endif()
 
 #-----------------------------------------------------------------------------#

Diff for: doc/example/geant4.rst

@@ -32,7 +32,7 @@ The key components are global :cpp:struct:`celeritas::SetupOptions` and
 CMake infrastructure
 --------------------
 
-.. literalinclude:: ../../example/accel/CMakeLists.txt
+.. literalinclude:: ../../example/geant4/CMakeLists.txt
    :language: cmake
    :start-at: project(
    :end-before: END EXAMPLE CODE
@@ -51,17 +51,17 @@ Offload using a concrete G4VTrackingManager
 The tracking manager is the preferred way of offloading tracks to Celeritas. It
 requires Geant4 11.0 or higher.
 
-.. literalinclude:: ../../example/accel/trackingmanager-offload.cc
+.. literalinclude:: ../../example/geant4/trackingmanager-offload.cc
    :start-at: #include
 
 Offload using a concrete G4UserTrackingAction
 ---------------------------------------------
 
-.. literalinclude:: ../../example/accel/simple-offload.cc
+.. literalinclude:: ../../example/geant4/simple-offload.cc
    :start-at: #include
 
 Offload using a concrete G4VFastSimulationModel
 -----------------------------------------------
 
-.. literalinclude:: ../../example/accel/fastsim-offload.cc
+.. literalinclude:: ../../example/geant4/fastsim-offload.cc
    :start-at: #include

Diff for: doc/usage/integration.rst

@@ -21,28 +21,28 @@ recommended for all applications that support Geant4 11.0 or higher.
 1. Find and link in your CMake project:
 
    - Find the Celeritas package.
-   - Link ``Celeritas::accel`` .
+   - Link ``Celeritas::G4`` .
    - Use ``celeritas_target_link_libraries`` instead of
      ``target_link_libraries`` when both VecGeom and CUDA are enabled.
 
 2. Set up physics offloading in your "main" function.
 
+   - Include ``<CeleritasG4.hh>``
    - Register the ``TrackingManagerConstructor``, which tells Geant4 to send EM
      tracks to Celeritas rather than the main tracking loop.
    - Tweak the ``SetupOptions`` based on problem requirements, or use the
      :ref:`g4_ui_macros`.
 
 3. Add hooks to safely set up and tear down Celeritas and its GPU code.
 
-   - Initialize logging in ``UserActionInitialization``, using
-     ``BuildForMaster`` (MT mode) or ``Build`` (serial).
-   - In ``UserRunAction``, ``BeginOfRunAction`` initializes problem data
-     (master or serial) and local state (worker or serial), and
-     ``EndOfRunAction`` safely deallocates everything.
+   - Call ``BeginOfRunAction`` at the beginning of the run to initialize
+     problem data (master or serial) and local state (worker or serial).
+   - Call ``EndOfRunAction`` at the end of the run to safely deallocate
+     everything.
 
 The changes for a simple application look like:
 
-.. literalinclude:: ../../example/accel/add-celer.diff
+.. literalinclude:: ../../example/geant4/add-celer.diff
    :language: diff
 
 CMake integration

Diff for: example/accel/add-celer.diff

@@ -17,7 +17,7 @@ endif()
 
 add_executable(simple-offload simple-offload.cc)
 celeritas_target_link_libraries(simple-offload
-  Celeritas::accel
+  Celeritas::G4
   ${Geant4_LIBRARIES}
 )
 
@@ -27,7 +27,7 @@ endif()
 
 add_executable(fastsim-offload fastsim-offload.cc)
 celeritas_target_link_libraries(fastsim-offload
-  Celeritas::accel
+  Celeritas::G4
   ${Geant4_LIBRARIES}
 )
 
@@ -36,7 +36,7 @@ if(Geant4_VERSION VERSION_LESS 11.0)
 else()
   add_executable(trackingmanager-offload trackingmanager-offload.cc)
   celeritas_target_link_libraries(trackingmanager-offload
-    Celeritas::accel
+    Celeritas::G4
     ${Geant4_LIBRARIES}
   )
 endif()

Diff for: example/accel/.gitignore renamed to example/geant4/.gitignore

@@ -0,0 +1,37 @@
+diff --git example/geant4/trackingmanager-offload.cc example/geant4/trackingmanager-offload.cc
+index f11c900f0..8fda9cd09 100644
+--- example/geant4/trackingmanager-offload.cc
++++ example/geant4/trackingmanager-offload.cc
+@@ -31,2 +31,5 @@
+ 
++// Celeritas
++#include <CeleritasG4.hh>
++
+ // Celeritas convenience utils
+@@ -35,2 +38,4 @@
+ 
++using TMI = celeritas::TrackingManagerIntegration;
++
+ namespace
+@@ -133,2 +138,3 @@ class RunAction final : public G4UserRunAction
+     {
++        TMI::Instance().BeginOfRunAction(run);
+     }
+@@ -136,2 +142,3 @@ class RunAction final : public G4UserRunAction
+     {
++        TMI::Instance().EndOfRunAction(run);
+     }
+@@ -213,4 +220,8 @@ int main()
+ 
++    auto& tmi = TMI::Instance();
++
+     // Use FTFP_BERT, but use Celeritas tracking for e-/e+/g
+     auto* physics_list = new FTFP_BERT{/* verbosity = */ 0};
++    physics_list->RegisterPhysics(
++        new celeritas::TrackingManagerConstructor(&tmi));
+     run_manager->SetUserInitialization(physics_list);
+@@ -218,2 +229,4 @@ int main()
+ 
++    tmi.SetOptions(MakeOptions());
++
+     run_manager->Initialize();

Diff for: example/accel/CMakeLists.txt renamed to example/geant4/CMakeLists.txt

@@ -2,12 +2,14 @@
 // Copyright Celeritas contributors: see top-level COPYRIGHT file for details
 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
 //---------------------------------------------------------------------------//
-//! \file accel/fastsim-offload.cc
+//! \file geant4/fastsim-offload.cc
 //---------------------------------------------------------------------------//
 
 #include <algorithm>
 #include <iterator>
 #include <type_traits>
+
+// Geant4
 #include <FTFP_BERT.hh>
 #include <G4Box.hh>
 #include <G4Electron.hh>
@@ -41,11 +43,10 @@
 #    include <G4MTRunManager.hh>
 #endif
 
-#include <accel/AlongStepFactory.hh>
-#include <accel/FastSimulationIntegration.hh>
-#include <accel/FastSimulationModel.hh>
-#include <accel/SetupOptions.hh>
-#include <corecel/Macros.hh>
+// Celeritas
+#include <CeleritasG4.hh>
+
+// Utility includes
 #include <corecel/io/Logger.hh>
 
 using celeritas::FastSimulationIntegration;
@@ -130,20 +131,9 @@ class RunAction final : public G4UserRunAction
 class ActionInitialization final : public G4VUserActionInitialization
 {
   public:
-    void BuildForMaster() const final
-    {
-        FastSimulationIntegration::Instance().BuildForMaster();
-
-        CELER_LOG_LOCAL(status) << "Constructing user actions";
-
-        this->SetUserAction(new RunAction{});
-    }
+    void BuildForMaster() const final { this->SetUserAction(new RunAction{}); }
     void Build() const final
     {
-        FastSimulationIntegration::Instance().Build();
-
-        CELER_LOG_LOCAL(status) << "Constructing user actions";
-
         this->SetUserAction(new PrimaryGeneratorAction{});
         this->SetUserAction(new RunAction{});
     }