refactor: Improve logging, configuration and doc of G4 surface mapping (

#1589)

This should help if someone tries to match a G4 geometry with a `Acts::TrackingGeometry`.

Examples/Algorithms/Geant4/include/ActsExamples/Geant4/SensitiveSurfaceMapper.hpp

@@ -27,6 +27,9 @@ namespace ActsExamples {
 /// it such that name will be containing the mapping prefix
 /// and the Acts::GeometryIdentifier of the surface.
 ///
+/// The mapping is done by matching the position of the G4 physical volume with
+/// the center position of an Acts::Surface.
+///
 /// This allows to directly associate Geant4 hits to the sensitive
 /// elements of the Acts::TrackingGeoemtry w/o map lookup.
 class SensitiveSurfaceMapper {
@@ -35,9 +38,13 @@ class SensitiveSurfaceMapper {
 
   /// Configuration struct for the surface mapper
   struct Config {
+    /// For which G4 material names we try to find a mapping
     std::vector<std::string> materialMappings = {"Silicon"};
+
+    /// For which G4 volume names we try to find a mapping
     std::vector<std::string> volumeMappings = {};
 
+    /// The tracking geometry we try to map
     std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry = nullptr;
   };
 

Examples/Algorithms/Geant4/src/SensitiveSurfaceMapper.cpp

@@ -88,10 +88,23 @@ void ActsExamples::SensitiveSurfaceMapper::remapSensitiveNames(
         ++sCounter;
         std::string mappedVolumeName = SensitiveSurfaceMapper::mappingPrefix;
         mappedVolumeName += std::to_string(mappedSurface->geometryId().value());
-        ACTS_VERBOSE("Remap sensitive volume: " << g4PhysicalVolume->GetName());
-        ACTS_VERBOSE("                    to: " << mappedVolumeName);
+        ACTS_VERBOSE("Found matching surface " << mappedSurface->geometryId()
+                                               << " at position "
+                                               << g4RelPosition.transpose());
+        ACTS_VERBOSE("Remap: " << g4PhysicalVolume->GetName() << " -> "
+                               << mappedVolumeName);
         g4PhysicalVolume->SetName(mappedVolumeName.c_str());
+      } else {
+        ACTS_VERBOSE("No mapping found for '"
+                     << volumeName << "' with material '" << volumeMaterialName
+                     << "' at position " << g4RelPosition.transpose());
       }
+    } else {
+      ACTS_VERBOSE(
+          "Did not try mapping '"
+          << g4PhysicalVolume->GetName() << "' at " << g4RelPosition.transpose()
+          << " because g4SensitiveDetector is nullptr"
+          << " and none of the provided volumes or materials were found");
     }
   } else {
     // Step down to all daughters

Examples/Python/src/Geant4Component.cpp

@@ -149,7 +149,9 @@ PYBIND11_MODULE(ActsPythonBindingsGeant4, mod) {
       [](Acts::Logging::Level& level, G4VUserDetectorConstruction* detector,
          const std::string& inputParticles,
          std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry,
-         std::shared_ptr<const Acts::MagneticFieldProvider> magneticField) {
+         std::shared_ptr<const Acts::MagneticFieldProvider> magneticField,
+         const std::vector<std::string>& volumeMappings,
+         const std::vector<std::string>& materialMappings) {
         // The Geant4 actions needed
         std::vector<G4UserRunAction*> runActions = {};
         std::vector<G4UserEventAction*> eventActions = {};
@@ -203,6 +205,15 @@ PYBIND11_MODULE(ActsPythonBindingsGeant4, mod) {
         if (trackingGeometry) {
           SensitiveSurfaceMapper::Config ssmCfg;
           ssmCfg.trackingGeometry = trackingGeometry;
+
+          // Take the default args if nothing provided
+          if (not volumeMappings.empty()) {
+            ssmCfg.volumeMappings = volumeMappings;
+          }
+          if (not materialMappings.empty()) {
+            ssmCfg.materialMappings = materialMappings;
+          }
+
           g4Cfg.sensitiveSurfaceMapper =
               std::make_shared<const SensitiveSurfaceMapper>(
                   ssmCfg,
@@ -212,8 +223,9 @@ PYBIND11_MODULE(ActsPythonBindingsGeant4, mod) {
         return g4Cfg;
       },
       "level"_a, "detector"_a, "inputParticles"_a,
-      py::arg("trackingGeometry") = nullptr,
-      py::arg("magneticField") = nullptr);
+      py::arg("trackingGeometry") = nullptr, py::arg("magneticField") = nullptr,
+      py::arg("volumeMappings") = std::vector<std::string>{},
+      py::arg("materialMappings") = std::vector<std::string>{});
 
   Acts::Python::Context ctx;
   ctx.modules["geant4"] = &mod;