feat: Add a SurfaceHandle class to manage surface references

Core/include/Acts/Detector/Detector.hpp

@@ -64,7 +64,7 @@ class Detector : public std::enable_shared_from_this<Detector> {
   /// @note Only call this if you need shared ownership of this object.
   ///
   /// @return The shared pointer
-  std::shared_ptr<Detector> getSharedPtr();
+  std::shared_ptr<Detector> getHandle();
 
   /// Retrieve a @c std::shared_ptr for this surface (const version)
   ///
@@ -75,7 +75,7 @@ class Detector : public std::enable_shared_from_this<Detector> {
   /// @note Only call this if you need shared ownership of this object.
   ///
   /// @return The shared pointer
-  std::shared_ptr<const Detector> getSharedPtr() const;
+  std::shared_ptr<const Detector> getHandle() const;
 
   /// Non-const access to the root volumes
   ///

Core/include/Acts/Detector/DetectorComponents.hpp

@@ -78,7 +78,7 @@ struct ExternalStructure {
 /// of contained volumes.
 struct InternalStructure {
   /// Contained surfaces of this volume, handled by the surfacesUpdater
-  std::vector<std::shared_ptr<Surface>> surfaces = {};
+  std::vector<SurfaceHandle<Surface>> surfaces = {};
   /// Contained volumes of this volume, handled by the volumeUpdater
   std::vector<std::shared_ptr<DetectorVolume>> volumes = {};
   /// Navigation delegate for surfaces

Core/include/Acts/Detector/DetectorVolume.hpp

@@ -37,6 +37,9 @@
 namespace Acts {
 
 class Surface;
+
+template <class T>
+class SurfaceHandle;
 class IVolumeMaterial;
 class VolumeBounds;
 
@@ -111,7 +114,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   DetectorVolume(const GeometryContext& gctx, std::string name,
                  const Transform3& transform,
                  std::shared_ptr<VolumeBounds> bounds,
-                 std::vector<std::shared_ptr<Surface>> surfaces,
+                 std::vector<SurfaceHandle<Surface>> surfaces,
                  std::vector<std::shared_ptr<DetectorVolume>> volumes,
                  ExternalNavigationDelegate externalNavigation,
                  InternalNavigationDelegate internalNavigation) noexcept(false);
@@ -134,7 +137,6 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
 
   // === Factory Methods ===
 
-  /// @fn static std::shared_ptr<DetectorVolume> makeShared(const GeometryContext& gctx, std::string name, const Transform3& transform, std::shared_ptr<VolumeBounds> bounds, std::vector<std::shared_ptr<Surface>> surfaces, std::vector<std::shared_ptr<DetectorVolume>> volumes, ExternalNavigationDelegate externalNavigation, InternalNavigationDelegate internalNavigation)
   /// @brief Protected factory method for producing memory managed instances of DetectorVolume.
   ///
   /// This overload creates a detector volume with full navigation capabilities,
@@ -146,7 +148,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   /// @param name The name of the detector volume
   /// @param transform The transform3 object of the volume
   /// @param bounds Shared pointer to the volume bounds
-  /// @param surfaces Vector of shared pointers to surfaces
+  /// @param surfaces Vector of surface handles to surfaces
   /// @param volumes Vector of shared pointers to sub-volumes
   /// @param externalNavigation The external navigation delegate
   /// @param internalNavigation The internal navigation delegate
@@ -159,7 +161,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   static std::shared_ptr<DetectorVolume> makeShared(
       const GeometryContext& gctx, std::string name,
       const Transform3& transform, std::shared_ptr<VolumeBounds> bounds,
-      std::vector<std::shared_ptr<Surface>> surfaces,
+      std::vector<SurfaceHandle<Surface>> surfaces,
       std::vector<std::shared_ptr<DetectorVolume>> volumes,
       ExternalNavigationDelegate externalNavigation,
       InternalNavigationDelegate internalNavigation);
@@ -197,7 +199,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   /// @note Only call this if you need shared ownership of this object.
   ///
   /// @return The shared pointer
-  std::shared_ptr<DetectorVolume> getSharedPtr();
+  std::shared_ptr<DetectorVolume> getHandle();
 
   /// Retrieve a @c std::shared_ptr for this surface (const version)
   ///
@@ -208,7 +210,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   /// @note Only call this if you need shared ownership of this object.
   ///
   /// @return The shared pointer
-  std::shared_ptr<const DetectorVolume> getSharedPtr() const;
+  std::shared_ptr<const DetectorVolume> getHandle() const;
 
   /// Const access to the transform
   ///
@@ -284,7 +286,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   /// Non-const access to the surfaces
   ///
   /// @return the surfaces shared pointer store
-  std::vector<std::shared_ptr<Surface>>& surfacePtrs();
+  std::vector<SurfaceHandle<Surface>>& surfacePtrs();
 
   /// Non-const access to the volumes
   ///
@@ -405,7 +407,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   ///
   void assignInternalNavigation(
       InternalNavigationDelegate internalNavigation,
-      const std::vector<std::shared_ptr<Surface>>& surfaces = {},
+      const std::vector<SurfaceHandle<Surface>>& surfaces = {},
       const std::vector<std::shared_ptr<DetectorVolume>>& volumes = {});
 
   /// Const access to the navigation state updator
@@ -497,7 +499,7 @@ class DetectorVolume : public std::enable_shared_from_this<DetectorVolume> {
   ObjectStore<std::shared_ptr<Portal>> m_portals;
 
   /// Surface store (internal/external)
-  ObjectStore<std::shared_ptr<Surface>> m_surfaces;
+  ObjectStore<SurfaceHandle<Surface>> m_surfaces;
 
   /// Volume store (internal/external)
   ObjectStore<std::shared_ptr<DetectorVolume>> m_volumes;
@@ -544,7 +546,7 @@ class DetectorVolumeFactory {
       const PortalGenerator& portalGenerator, const GeometryContext& gctx,
       const std::string& name, const Transform3& transform,
       std::shared_ptr<VolumeBounds> bounds,
-      const std::vector<std::shared_ptr<Surface>>& surfaces,
+      const std::vector<SurfaceHandle<Surface>>& surfaces,
       const std::vector<std::shared_ptr<DetectorVolume>>& volumes,
       ExternalNavigationDelegate externalNavigation,
       InternalNavigationDelegate internalNavigation, int nSeg = -1) {

Core/include/Acts/Detector/KdtSurfacesProvider.hpp

@@ -34,14 +34,13 @@ template <std::size_t kDIM = 2u, std::size_t bSize = 100u,
 class KdtSurfaces {
  public:
   /// Broadcast the surface KDT type
-  using KDTS =
-      KDTree<kDIM, std::shared_ptr<Surface>, double, std::array, bSize>;
+  using KDTS = KDTree<kDIM, SurfaceHandle<Surface>, double, std::array, bSize>;
 
   /// Broadcast the query definition
   using Query = std::array<double, kDIM>;
 
   /// Broadcast the entry
-  using Entry = std::pair<Query, std::shared_ptr<Surface>>;
+  using Entry = std::pair<Query, SurfaceHandle<Surface>>;
 
   /// Constructor from a vector of surfaces
   ///
@@ -50,7 +49,7 @@ class KdtSurfaces {
   /// @param casts the cast list from global position into kdtree local
   /// @param rgen the reference point generator
   KdtSurfaces(const GeometryContext& gctx,
-              const std::vector<std::shared_ptr<Surface>>& surfaces,
+              const std::vector<SurfaceHandle<Surface>>& surfaces,
               const std::array<AxisDirection, kDIM>& casts,
               const reference_generator& rgen =
                   detail::PolyhedronReferenceGenerator<1u, false>{})
@@ -86,10 +85,10 @@ class KdtSurfaces {
   /// @param range is the range to be queried
   ///
   /// @return the matching surfaces from the KDT structure
-  std::vector<std::shared_ptr<Surface>> surfaces(
+  std::vector<SurfaceHandle<Surface>> surfaces(
       const RangeXD<kDIM, double>& range) const {
     // Strip the surfaces
-    std::vector<std::shared_ptr<Surface>> surfacePtrs;
+    std::vector<SurfaceHandle<Surface>> surfacePtrs;
     auto surfaceQuery = m_kdt->rangeSearchWithKey(range);
     std::ranges::for_each(
         surfaceQuery, [&](auto& surf) { surfacePtrs.push_back(surf.second); });
@@ -101,7 +100,7 @@ class KdtSurfaces {
   /// @param extent is the range Extent to be queried
   ///
   /// @return the matching surfaces fpulled from the KDT structure
-  std::vector<std::shared_ptr<Surface>> surfaces(const Extent& extent) const {
+  std::vector<SurfaceHandle<Surface>> surfaces(const Extent& extent) const {
     RangeXD<kDIM, double> qRange;
     for (auto [ibv, v] : enumerate(m_casts)) {
       qRange[ibv] = extent.range(v);
@@ -184,7 +183,7 @@ class KdtSurfacesProvider : public ISurfacesProvider {
   /// The call to provide the surfaces
   /// @param gctx Geometry context (not used in KDT provider)
   /// @return Vector of surfaces from the KDT query
-  std::vector<std::shared_ptr<Surface>> surfaces(
+  std::vector<SurfaceHandle<Surface>> surfaces(
       [[maybe_unused]] const GeometryContext& gctx) const final {
     return m_kdt->surfaces(m_region);
   }

Core/include/Acts/Detector/LayerStructureBuilder.hpp

@@ -57,19 +57,19 @@ class LayerStructureBuilder : public IInternalStructureBuilder {
    public:
     /// Constructor with predefined surfaces
     /// @param isurfaces is the vector of surfaces
-    explicit SurfacesHolder(std::vector<std::shared_ptr<Surface>> isurfaces)
+    explicit SurfacesHolder(std::vector<SurfaceHandle<Surface>> isurfaces)
         : m_surfaces(std::move(isurfaces)) {}
 
     /// Return the surfaces from the holder
     /// @param gctx is the geometry context
     /// @return Vector of surfaces held by this holder
-    std::vector<std::shared_ptr<Surface>> surfaces(
+    std::vector<SurfaceHandle<Surface>> surfaces(
         [[maybe_unused]] const GeometryContext& gctx) const final {
       return m_surfaces;
     }
 
    private:
-    std::vector<std::shared_ptr<Surface>> m_surfaces = {};
+    std::vector<SurfaceHandle<Surface>> m_surfaces = {};
   };
 
   /// @brief Configuration struct for the LayerStructureBuilder

Core/include/Acts/Detector/MultiWireStructureBuilder.hpp

@@ -22,6 +22,13 @@
 #include <tuple>
 #include <vector>
 
+namespace Acts {
+
+template <class T>
+class SurfaceHandle;
+
+}
+
 namespace Acts::Experimental {
 
 class MultiWireStructureBuilder {
@@ -33,7 +40,7 @@ class MultiWireStructureBuilder {
     std::string name = "";
 
     /// The surfaces of the Multi Wire
-    std::vector<std::shared_ptr<Acts::Surface>> mlSurfaces = {};
+    std::vector<SurfaceHandle<Acts::Surface>> mlSurfaces = {};
 
     /// The transform of the Multi Wire
     Transform3 transform = Transform3::Identity();

Core/include/Acts/Detector/Portal.hpp

@@ -24,6 +24,9 @@ namespace Acts {
 class ISurfaceMaterial;
 class Surface;
 
+template <class T>
+class SurfaceHandle;
+
 namespace Experimental {
 
 class DetectorVolume;
@@ -42,7 +45,7 @@ class Portal {
   /// Constructor from surface w/o portal links
   ///
   /// @param surface is the representing surface
-  explicit Portal(std::shared_ptr<RegularSurface> surface);
+  explicit Portal(SurfaceHandle<RegularSurface> surface);
 
   /// The vector of attached volumes forward/backward, this is useful in the
   /// geometry building
@@ -147,7 +150,7 @@ class Portal {
 
  private:
   /// The surface representation of this portal
-  std::shared_ptr<RegularSurface> m_surface;
+  SurfaceHandle<RegularSurface> m_surface;
 
   /// The portal targets along/opposite the normal vector
   std::array<ExternalNavigationDelegate, 2u> m_portalNavigation = {

Core/include/Acts/Detector/ProtoSupport.hpp

@@ -19,6 +19,13 @@
 #include <stdexcept>
 #include <vector>
 
+namespace Acts {
+
+template <class T>
+class SurfaceHandle;
+
+}
+
 namespace Acts::Experimental {
 /// @brief Support surface building instructions
 ///
@@ -60,7 +67,7 @@ struct ProtoSupport {
   // Building instructions 2 (surface is provided):
 
   /// The support surface can already be provided
-  std::shared_ptr<Surface> surface = nullptr;
+  Acts::SurfaceHandle<Surface> surface = {};
 
   /// The (optional) binning description for proto material
   std::optional<std::vector<ProtoAxis>> protoMaterialBinning = std::nullopt;

Core/include/Acts/Detector/detail/SupportSurfacesHelper.hpp

@@ -124,7 +124,7 @@ struct RectangularSupport {
 /// @param splits the number of surfaces through which the surface is approximated (1u ... cylinder)
 ///
 /// @return a vector of surfaces that represent this support
-std::vector<std::shared_ptr<Surface>> cylindricalSupport(
+std::vector<SurfaceHandle<Surface>> cylindricalSupport(
     const SupportSurfaceComponents& components, unsigned int splits = 1u);
 
 /// @brief Helper method to build disc support structure
@@ -133,15 +133,15 @@ std::vector<std::shared_ptr<Surface>> cylindricalSupport(
 /// @param splits the number of surfaces through which the surface is approximated (1u ... disc)
 ///
 /// @return a vector of surfaces that represent this support
-std::vector<std::shared_ptr<Surface>> discSupport(
+std::vector<SurfaceHandle<Surface>> discSupport(
     const SupportSurfaceComponents& components, unsigned int splits = 1u);
 
 /// @brief Helper method to build planar support structure
 ///
 /// @param components are the components generated by the SurfaceComponentsCreator function
 ///
 /// @return a vector of surfaces that represent this support
-std::vector<std::shared_ptr<Surface>> rectangularSupport(
+std::vector<SurfaceHandle<Surface>> rectangularSupport(
     const SupportSurfaceComponents& components);
 
 /// Add support to already existing surfaces
@@ -153,7 +153,7 @@ std::vector<std::shared_ptr<Surface>> rectangularSupport(
 /// @param supportSplits the number of splits if splitting is configured
 ///
 /// @note this modifies the layerSurfaces and toAllIndices
-void addSupport(std::vector<std::shared_ptr<Surface>>& layerSurfaces,
+void addSupport(std::vector<SurfaceHandle<Surface>>& layerSurfaces,
                 std::vector<std::size_t>& assignToAll,
                 const Extent& layerExtent,
                 const SurfaceComponentsCreator& componentCreator,

Core/include/Acts/Detector/interface/ISurfacesProvider.hpp

@@ -17,6 +17,9 @@ namespace Acts {
 
 class Surface;
 
+template <class T>
+class SurfaceHandle;
+
 namespace Experimental {
 
 /// @brief This is the interface for providing surfaces
@@ -35,7 +38,7 @@ class ISurfacesProvider {
   /// @param gctx the geometry context at the creation of the internal structure
   ///
   /// @return a shared detector object
-  virtual std::vector<std::shared_ptr<Surface>> surfaces(
+  virtual std::vector<SurfaceHandle<Surface>> surfaces(
       const GeometryContext& gctx) const = 0;
 };
 

Core/include/Acts/EventData/GenericBoundTrackParameters.hpp

@@ -15,6 +15,7 @@
 #include "Acts/EventData/detail/PrintParameters.hpp"
 #include "Acts/Surfaces/CurvilinearSurface.hpp"
 #include "Acts/Surfaces/Surface.hpp"
+#include "Acts/Surfaces/SurfaceHandle.hpp"
 #include "Acts/Utilities/UnitVectors.hpp"
 #include "Acts/Utilities/detail/periodic.hpp"
 
@@ -61,7 +62,7 @@ class GenericBoundTrackParameters {
   /// @note The returned result indicates whether the free parameters could
   /// successfully be converted to on-surface parameters.
   static Result<GenericBoundTrackParameters> create(
-      const GeometryContext& geoCtx, std::shared_ptr<const Surface> surface,
+      const GeometryContext& geoCtx, SurfaceHandle<const Surface> surface,
       const Vector4& pos4, const Vector3& dir, double qOverP,
       std::optional<CovarianceMatrix> cov,
       ParticleHypothesis particleHypothesis,
@@ -92,7 +93,8 @@ class GenericBoundTrackParameters {
       std::optional<CovarianceMatrix> cov,
       ParticleHypothesis particleHypothesis) {
     return GenericBoundTrackParameters(
-        CurvilinearSurface(pos4.segment<3>(ePos0), dir).surface(),
+        SurfaceHandle<const Surface>(
+            CurvilinearSurface(pos4.segment<3>(ePos0), dir).surface()),
         transformFreeToCurvilinearParameters(pos4[eTime], dir, qOverP),
         std::move(cov), std::move(particleHypothesis));
   }
@@ -130,7 +132,7 @@ class GenericBoundTrackParameters {
   /// an input here to be consistent with the other constructors below that
   /// that also take the charge as an input. The charge sign is only used in
   /// debug builds to check for consistency with the q/p parameter.
-  GenericBoundTrackParameters(std::shared_ptr<const Surface> surface,
+  GenericBoundTrackParameters(SurfaceHandle<const Surface> surface,
                               const ParametersVector& params,
                               std::optional<CovarianceMatrix> cov,
                               ParticleHypothesis particleHypothesis)
@@ -151,7 +153,7 @@ class GenericBoundTrackParameters {
   explicit GenericBoundTrackParameters(
       const GenericBoundTrackParameters<other_particle_hypothesis_t>& other)
       : GenericBoundTrackParameters(
-            other.referenceSurface().getSharedPtr(), other.parameters(),
+            other.referenceSurface().getHandle(), other.parameters(),
             other.covariance(),
             ParticleHypothesis{other.particleHypothesis()}) {}
 
@@ -337,7 +339,7 @@ class GenericBoundTrackParameters {
   BoundVector m_params;
   std::optional<BoundSquareMatrix> m_cov;
   /// reference surface
-  std::shared_ptr<const Surface> m_surface;
+  SurfaceHandle<const Surface> m_surface;
   // TODO use [[no_unique_address]] once we switch to C++20
   ParticleHypothesis m_particleHypothesis;