Add example offloading template

doc/example/geant4.rst

@@ -3,8 +3,16 @@
 
 .. _example_geant:
 
-Geant4 integration example
-==========================
+Geant4 integration examples
+===========================
+
+Offload template
+----------------
+
+.. include:: ../../example/offload-template/README.rst
+
+Small executables
+-----------------
 
 These small examples demonstrate how to offload tracks to Celeritas in a serial
 or multithreaded environment using:

example/offload-template/.gitignore

@@ -0,0 +1,2 @@
+/build
+/install

example/offload-template/CMakeLists.txt

@@ -0,0 +1,53 @@
+#------------------------------- -*- cmake -*- -------------------------------#
+# Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+#-----------------------------------------------------------------------------#
+# Minimal Geant4 application with Celeritas offloading capabilities
+#-----------------------------------------------------------------------------#
+cmake_minimum_required(VERSION 3.10)
+cmake_policy(VERSION 3.12...3.30)
+project(offload-template)
+
+#-----------------------------------------------------------------------------#
+# Find packages
+find_package(Celeritas 0.5)
+find_package(Geant4 REQUIRED)
+
+if(NOT Celeritas_FOUND)
+  message(FATAL_ERROR
+  "No Celeritas installation found.\n"
+  "Export Celeritas_ROOT=/path/to/celeritas/install or use CMAKE_INSTALL_PREFIX")
+endif()
+
+#-----------------------------------------------------------------------------#
+# Set up sources, include directories, and libraries
+set(_sources
+  src/ActionInitialization.cc
+  src/Celeritas.cc
+  src/DetectorConstruction.cc
+  src/EventAction.cc
+  src/PrimaryGeneratorAction.cc
+  src/RunAction.cc
+  src/SensitiveDetector.cc
+)
+
+set(_includes
+  ${CMAKE_CURRENT_SOURCE_DIR}/src
+  ${Geant4_INCLUDE_DIR}
+  ${Celeritas_ROOT}/include
+)
+
+set(_libs
+  ${Geant4_LIBRARIES}
+  Celeritas::celeritas
+  Celeritas::accel
+)
+
+#-----------------------------------------------------------------------------#
+# Add executable
+add_executable(run-offload main.cc ${_sources})
+target_include_directories(run-offload PRIVATE $<BUILD_INTERFACE:${_includes}>)
+
+# Use Celeritas CUDA RDC utility function to correctly link libraries
+include(CudaRdcUtils)
+cuda_rdc_target_link_libraries(run-offload ${_libs})

example/offload-template/README.rst

@@ -0,0 +1,65 @@
+====================================
+Geant4-Celeritas offloading template
+====================================
+
+Template for Geant4 applications with Celeritas physics offloading capabilities.
+It shows how to link Celeritas against Geant4 in the :code:`CMakeLists.txt` and
+the Geant4 classes needed to initialize Celeritas, offload events, and recover
+step information.
+
+Dependencies
+------------
+
+- Geant4 v11 or newer
+- Celeritas v0.5 or newer
+
+  - :code:`CELERITAS_USE_Geant4=ON`
+
+Build and run
+-------------
+
+.. code-block:: sh
+
+   $ mkdir build
+   $ cd build
+   $ cmake ..
+   $ make
+   $ export CELER_DISABLE_PARALLEL=1
+   $ ./run-offload
+
+
+Boilerplate offloading code
+---------------------------
+
+- :code:`Celeritas.[hh/cc]`: Defines the needed components for a Celeritas
+offload execution:
+
+  - **Setup options** (memory allocation, physics, field, scoring, and so on)
+  - **Shared parameters** used in the run (materials, physics processes
+    cross-section tables, and so on)
+  - **Transporter** (execute/manage the particle transport)
+  - **Simple Offload** simplified user-interface. Each `SimpleOffload` call is
+    briefly described below.
+
+- :code:`G4VUserActionInitialization`
+
+  - :code:`Build`: Construct Celeritas Simple Offload interface with
+    user-defined options (from `Celeritas.cc`) and assign the Celeritas tracking
+    manager to the appropriate particles
+
+- :code:`G4UserRunAction`
+
+  - :code:`BeginOfRunAction`: Initialize Celeritas global shared data on master
+    and worker threads
+  - :code:`EndOfRunAction`: Clear data and return Celeritas to an invalid state
+
+- :code:`G4UserEventAction`
+
+  - :code:`BeginOfEventAction`: Initialize event in Celeritas
+  - :code:`EndOfEventAction`: Flush remaining particles
+
+- :code:`G4VSensitiveDetector`
+
+  - :code:`ProcessHits`: Currently the *only* Celeritas callback interface to
+    Geant4; at each step, Celeritas sends data back as a `G4Step` to be
+    processed by Geant4

example/offload-template/main.cc

@@ -0,0 +1,43 @@
+//------------------------------- -*- C++ -*- -------------------------------//
+// Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+//---------------------------------------------------------------------------//
+//! \file example/offload-template/main.cc
+//! \brief Minimal Geant4 application with Celeritas offloading.
+//---------------------------------------------------------------------------//
+#include <FTFP_BERT.hh>
+#include <G4RunManager.hh>
+
+#include "src/ActionInitialization.hh"
+#include "src/DetectorConstruction.hh"
+
+//---------------------------------------------------------------------------//
+/*!
+ * Geant4-Celeritas offloading template.
+ *
+ * See README for details.
+ */
+int main(int argc, char* argv[])
+{
+    if (argc != 1)
+    {
+        // Print help message
+        std::cout << "Usage: " << argv[0] << std::endl;
+        return EXIT_FAILURE;
+    }
+
+    // Construct run manager
+    G4RunManager run_manager;
+    run_manager.SetVerboseLevel(1);  // Print minimal information about the run
+
+    // Initialize physics, geometry, and actions
+    run_manager.SetUserInitialization(new FTFP_BERT(/* verbosity = */ 0));
+    run_manager.SetUserInitialization(new DetectorConstruction());
+    run_manager.SetUserInitialization(new ActionInitialization());
+
+    // Run one event
+    run_manager.Initialize();
+    run_manager.BeamOn(1);
+
+    return EXIT_SUCCESS;
+}

example/offload-template/src/ActionInitialization.cc

@@ -0,0 +1,46 @@
+//------------------------------- -*- C++ -*- -------------------------------//
+// Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+//---------------------------------------------------------------------------//
+//! \file example/offload-template/src/ActionInitialization.cc
+//---------------------------------------------------------------------------//
+#include "ActionInitialization.hh"
+
+#include <accel/TrackingManagerOffload.hh>
+
+#include "Celeritas.hh"
+#include "EventAction.hh"
+#include "G4Electron.hh"
+#include "G4Gamma.hh"
+#include "G4Positron.hh"
+#include "PrimaryGeneratorAction.hh"
+#include "RunAction.hh"
+
+//---------------------------------------------------------------------------//
+/*!
+ * Construct empty.
+ */
+ActionInitialization::ActionInitialization() : G4VUserActionInitialization() {}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Set up all user actions and Celeritas offload interface.
+ */
+void ActionInitialization::Build() const
+{
+    // Construct Celeritas offloading interface
+    CelerSimpleOffload().Build(
+        &CelerSetupOptions(), &CelerSharedParams(), &CelerLocalTransporter());
+
+    // Add Celeritas tracking manager to electrons, positrons, and gammas
+    auto* celer_tracking = new celeritas::TrackingManagerOffload(
+        &CelerSharedParams(), &CelerLocalTransporter());
+    G4Electron::Definition()->SetTrackingManager(celer_tracking);
+    G4Positron::Definition()->SetTrackingManager(celer_tracking);
+    G4Gamma::Definition()->SetTrackingManager(celer_tracking);
+
+    // Initialize Geant4 user actions
+    this->SetUserAction(new RunAction());
+    this->SetUserAction(new EventAction());
+    this->SetUserAction(new PrimaryGeneratorAction());
+}

example/offload-template/src/ActionInitialization.hh

@@ -0,0 +1,23 @@
+//------------------------------- -*- C++ -*- -------------------------------//
+// Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+//---------------------------------------------------------------------------//
+//! \file example/offload-template/src/ActionInitialization.hh
+//---------------------------------------------------------------------------//
+#pragma once
+
+#include <G4VUserActionInitialization.hh>
+
+//---------------------------------------------------------------------------//
+/*!
+ * Initialize all user action classes.
+ */
+class ActionInitialization final : public G4VUserActionInitialization
+{
+  public:
+    // Construct empty
+    ActionInitialization();
+
+    // Set up user actions and construct Celeritas offload interface
+    void Build() const final;
+};

example/offload-template/src/Celeritas.cc

@@ -0,0 +1,87 @@
+//------------------------------- -*- C++ -*- -------------------------------//
+// Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+//---------------------------------------------------------------------------//
+//! \file example/offload-template/src/Celeritas.cc
+//---------------------------------------------------------------------------//
+#include "Celeritas.hh"
+
+#include <G4Threading.hh>
+#include <accel/AlongStepFactory.hh>
+#include <celeritas/alongstep/AlongStepGeneralLinearAction.hh>
+#include <celeritas/alongstep/AlongStepUniformMscAction.hh>
+#include <celeritas/field/UniformFieldData.hh>
+#include <celeritas/io/ImportData.hh>
+
+using namespace celeritas;
+
+//---------------------------------------------------------------------------//
+/*!
+ * Globally shared setup options.
+ * Setup options are constructed the first time this method is invoked.
+ */
+SetupOptions& CelerSetupOptions()
+{
+    static SetupOptions options = [] {
+        // See celeritas/install/include/accel/SetupOptions.hh
+        SetupOptions so;
+
+        // Set along-step factory
+        so.make_along_step = UniformAlongStepFactory();
+
+        so.max_num_tracks = 1024 * 16;
+        so.initializer_capacity = 1024 * 128 * 4;
+        so.secondary_stack_factor = 3.0;
+        so.ignore_processes = {"CoulombScat"};  // Ignored processes list
+
+        // Only call back for nonzero energy depositions: this is currently a
+        // global option for all detectors, so if any SDs extract data from
+        // tracks with no local energy deposition over the step, it must be set
+        // to false.
+        so.sd.ignore_zero_deposition = true;
+
+        // Using the pre-step point, reconstruct the G4 touchable handle.
+        so.sd.locate_touchable = true;
+        // Reconstruct the track, needed for particle type
+        so.sd.track = true;
+
+        // Save diagnostic information
+        so.output_file = "celeritas-offload-diagnostic.json";
+
+        // Pre/post-step data used in G4VSensitiveDetector::ProcessHits
+        so.sd.pre.kinetic_energy = true;
+        so.sd.post.kinetic_energy = true;
+        return so;
+    }();
+    return options;
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Celeritas problem data.
+ */
+SharedParams& CelerSharedParams()
+{
+    static SharedParams sp;
+    return sp;
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Thread-local (when supported) transporter.
+ */
+LocalTransporter& CelerLocalTransporter()
+{
+    static G4ThreadLocal LocalTransporter lt;
+    return lt;
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Thread-local offload interface.
+ */
+SimpleOffload& CelerSimpleOffload()
+{
+    static G4ThreadLocal SimpleOffload so;
+    return so;
+}

example/offload-template/src/Celeritas.hh

@@ -0,0 +1,28 @@
+//------------------------------- -*- C++ -*- -------------------------------//
+// Copyright Celeritas contributors: see top-level COPYRIGHT file for details
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+//---------------------------------------------------------------------------//
+//! \file example/offload-template/src/Celeritas.hh
+//---------------------------------------------------------------------------//
+#pragma once
+
+#include <accel/LocalTransporter.hh>
+#include <accel/SetupOptions.hh>
+#include <accel/SharedParams.hh>
+#include <accel/SimpleOffload.hh>
+
+namespace celeritas
+{
+class LocalTransporter;
+struct SetupOptions;
+class SharedParams;
+}  // namespace celeritas
+
+// Global shared setup options
+celeritas::SetupOptions& CelerSetupOptions();
+// Shared data and GPU setup
+celeritas::SharedParams& CelerSharedParams();
+// Thread-local transporter
+celeritas::LocalTransporter& CelerLocalTransporter();
+// Thread-local offload user interface
+celeritas::SimpleOffload& CelerSimpleOffload();