Set up the VecGeom BVH navigator and safety estimators for every volume

This lets GeometryManager set up VecGeom for Geant4 navigation as well as for the material budget.

- buildVecGeomGeometry() converts once and takes the assembly flattening as a parameter; the
  material budget keeps flattening.
- With a VecGeom that has BVHNavigatorV, volumes with more than two daughters get the BVH navigator
  and level locator, and every volume gets an explicit safety estimator.
- Without it the VecGeom v2 setup is unchanged.

https://gitlab.cern.ch/VecGeom/VecGeom/-/merge_requests/1547

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sawenzel

Detectors/Base/include/DetectorsBase/GeometryManager.h

@@ -135,6 +135,12 @@ class GeometryManager : public TObject
   /// Mean material budget between two points, using the VecGeom backend. On first call,
   /// lazily converts the currently loaded TGeo geometry to VecGeom (once per process).
   static o2::base::MatBudget vecGeomMaterialBudget(float x0, float y0, float z0, float x1, float y1, float z1);
+  /// Converts the currently loaded TGeo geometry to VecGeom and assigns a navigator, a level
+  /// locator and a safety estimator to every logical volume. Does the work once per process; later
+  /// calls, whatever they ask for, return the geometry already built, so a caller that needs a
+  /// particular assembly treatment must come first. \param flattenAssemblies dissolves TGeo
+  /// assemblies into their content.
+  static void buildVecGeomGeometry(bool flattenAssemblies);
 #else
   static constexpr bool isVecGeomAvailable() { return false; }
 #endif

Detectors/Base/src/GeometryManager.cxx

@@ -49,6 +49,14 @@
 #include <VecGeom/navigation/VNavigator.h>
 #include <VecGeom/volumes/LogicalVolume.h>
 #include <mutex>
+// The BVH navigator of the VNavigator family, which Geant4 navigation needs on every volume.
+#if __has_include(<VecGeom/navigation/BVHNavigatorV.h>)
+#define O2_VECGEOM_HAS_BVH_VNAVIGATOR
+#include <VecGeom/navigation/BVHNavigatorV.h>
+#include <VecGeom/navigation/BVHLevelLocator.h>
+#include <VecGeom/navigation/BVHSafetyEstimator.h>
+#include <VecGeom/navigation/SimpleSafetyEstimator.h>
+#endif
 #endif
 
 using namespace o2::detectors;
@@ -574,15 +582,22 @@ bool usesBvhAcceleration(vecgeom::LogicalVolume const* vol)
 /// process, the first time the VecGeom backend is requested. Not part of loadGeometry(),
 /// which every job calls regardless of whether it ever uses the VecGeom backend.
 void ensureVecGeomWorldBuilt()
+{
+  GeometryManager::buildVecGeomGeometry(true);
+}
+} // namespace
+
+void GeometryManager::buildVecGeomGeometry(bool flattenAssemblies)
 {
   static std::once_flag onceFlag;
-  std::call_once(onceFlag, []() {
+  std::call_once(onceFlag, [flattenAssemblies]() {
     if (!gGeoManager) {
       LOG(fatal) << "Cannot build VecGeom geometry: no TGeo geometry loaded (call GeometryManager::loadGeometry() first)";
     }
     // Translate geometry and material pointers, then build acceleration structures.
     tgeo2vecgeom::RootGeoManager::Instance().SetMaterialConversionHook([](TGeoMaterial const* m) { return (void*)m; });
-    tgeo2vecgeom::RootGeoManager::Instance().SetFlattenAssemblies(true);
+    LOG(info) << "VecGeom conversion: flattenAssemblies=" << flattenAssemblies;
+    tgeo2vecgeom::RootGeoManager::Instance().SetFlattenAssemblies(flattenAssemblies);
     tgeo2vecgeom::RootGeoManager::Instance().LoadRootGeometry();
 
     // Acceleration structures must be built before the navigators/locators reference them.
@@ -593,15 +608,28 @@ void ensureVecGeomWorldBuilt()
     // Builds a BVH per logical volume.
     vecgeom::BVHManager::Init();
 
-    // For each logical volume, set both a navigator (used for ComputeStep) and a matched
-    // level locator (used for point relocation after a boundary crossing via GlobalLocator).
+    // For each logical volume, set a navigator (used for ComputeStep), a matched level locator
+    // (used for point relocation after a boundary crossing via GlobalLocator) and, where the
+    // VNavigator family is complete, the safety estimator LogicalVolume::GetSafetyEstimator()
+    // hands out, which is separate from the one a navigator uses internally.
     for (auto& lvol : vecgeom::GeoManager::Instance().GetLogicalVolumesMap()) {
       auto* vol = lvol.second;
       if (!usesBvhAcceleration(vol)) {
         vol->SetNavigator(vecgeom::NewSimpleNavigator<>::Instance());
+#ifdef O2_VECGEOM_HAS_BVH_VNAVIGATOR
+        vol->SetLevelLocator(vol->ContainsAssembly() ? vecgeom::SimpleAssemblyLevelLocator::GetInstance()
+                                                     : vecgeom::SimpleLevelLocator::GetInstance());
+        vol->SetSafetyEstimator(vecgeom::SimpleSafetyEstimator::Instance());
+#else
         vol->SetLevelLocator(vecgeom::SimpleLevelLocator::GetInstance());
+#endif
       } else {
-#if VECGEOM_VERSION >= 0x020000
+#if defined(O2_VECGEOM_HAS_BVH_VNAVIGATOR)
+        vol->SetNavigator(vecgeom::BVHNavigatorV<>::Instance());
+        vol->SetLevelLocator(vol->ContainsAssembly() ? vecgeom::BVHAssemblyAwareLevelLocator::GetInstance()
+                                                     : vecgeom::BVHLevelLocator::GetInstance());
+        vol->SetSafetyEstimator(vecgeom::BVHSafetyEstimator::Instance());
+#elif VECGEOM_VERSION >= 0x020000
         // VecGeom 2 turned BVHNavigator into a plain class with static entry points instead of a
         // VNavigator singleton, so there is nothing to attach: vecGeomMaterialBudget() calls it
         // directly.
@@ -627,7 +655,6 @@ void ensureVecGeomWorldBuilt()
     }
   });
 }
-} // namespace
 
 //_____________________________________________________________________________________
 o2::base::MatBudget GeometryManager::vecGeomMaterialBudget(float x0, float y0, float z0, float x1, float y1, float z1)