feat(geo): TrackingVolume gets portal storage (#3673)

Part of #3502

### Enhancements to Geometry Handling:

* [`Core/include/Acts/Geometry/Portal.hpp`](diffhunk://#diff-5aadb8a97cbb4382fe684f28586c415cde1b4e467a7fec315c7506f9766133f3R215-R218): Added a mutable `surface()` method to the `Portal` class to allow modification of the portal surface.
* [`Core/src/Geometry/Portal.cpp`](diffhunk://#diff-e32791625fda93fd367fc971619ea03be19128e91bbca7e8a09b5af399beb461R175-R179): Implemented the mutable `surface()` method in the `Portal` class.

### Integration with TrackingVolume:

* `Core/include/Acts/Geometry/TrackingVolume.hpp`: 
  - Declared the `Portal` class.
  - Added methods to manage portals (`portals()`, `addPortal()`) and defined `PortalRange` and `MutablePortalRange` types. [[1]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR51) [[2]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR305-R324) [[3]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR518)
* `Core/src/Geometry/TrackingVolume.cpp`: 
  - Included the `Portal.hpp` header.
  - Implemented the portal management methods (`portals()`, `addPortal()`).
  - Updated `closeGeometry` to assign geometry IDs to portals. [[1]](diffhunk://#diff-a086b4ee3f623999c43c4f743425d97d2c10c9c902e73e8ee21fce615880a647R14) [[2]](diffhunk://#diff-a086b4ee3f623999c43c4f743425d97d2c10c9c902e73e8ee21fce615880a647R428-R439) [[3]](diffhunk://#diff-a086b4ee3f623999c43c4f743425d97d2c10c9c902e73e8ee21fce615880a647R657-R668)

Core/include/Acts/Geometry/Portal.hpp

@@ -212,6 +212,10 @@ class Portal {
   /// @return The portal surface
   const RegularSurface& surface() const;
 
+  /// Access the portal surface that is shared between the two links
+  /// @return The portal surface
+  RegularSurface& surface();
+
  private:
   /// Helper to check surface equivalence without checking material status. This
   /// is needed because we allow fusing portals with surfaces that are

Core/include/Acts/Geometry/TrackingVolume.hpp

@@ -48,6 +48,7 @@ class IVolumeMaterial;
 class Surface;
 class TrackingVolume;
 struct GeometryIdentifierHook;
+class Portal;
 
 /// Interface types of the Gen1 geometry model
 /// @note This interface is being replaced, and is subject to removal
@@ -301,6 +302,26 @@ class TrackingVolume : public Volume {
   /// @return the range of volumes
   MutableVolumeRange volumes();
 
+  using MutablePortalRange =
+      detail::TransformRange<detail::Dereference,
+                             std::vector<std::shared_ptr<Portal>>>;
+
+  using PortalRange =
+      detail::TransformRange<detail::ConstDereference,
+                             const std::vector<std::shared_ptr<Portal>>>;
+
+  /// Return all portals registered under this tracking volume
+  /// @return the range of portals
+  PortalRange portals() const;
+
+  /// Return mutable view of the registered portals under this tracking volume
+  /// @return the range of portals
+  MutablePortalRange portals();
+
+  /// Add a portal to this tracking volume
+  /// @param portal The portal to add
+  void addPortal(std::shared_ptr<Portal> portal);
+
   /// Add a child volume to this tracking volume
   /// @param volume The volume to add
   /// @note The @p volume will have its mother volume assigned to @p this.
@@ -494,6 +515,7 @@ class TrackingVolume : public Volume {
   std::string m_name;
 
   std::vector<std::unique_ptr<TrackingVolume>> m_volumes;
+  std::vector<std::shared_ptr<Portal>> m_portals;
 };
 
 }  // namespace Acts

Core/src/Geometry/Portal.cpp

@@ -172,6 +172,11 @@ const RegularSurface& Portal::surface() const {
   return *m_surface;
 }
 
+RegularSurface& Portal::surface() {
+  assert(m_surface != nullptr);
+  return *m_surface;
+}
+
 Portal Portal::merge(const GeometryContext& gctx, Portal& aPortal,
                      Portal& bPortal, BinningValue direction,
                      const Logger& logger) {

Core/src/Geometry/TrackingVolume.cpp

@@ -11,6 +11,7 @@
 #include "Acts/Definitions/Direction.hpp"
 #include "Acts/Geometry/GeometryIdentifier.hpp"
 #include "Acts/Geometry/GlueVolumesDescriptor.hpp"
+#include "Acts/Geometry/Portal.hpp"
 #include "Acts/Geometry/VolumeBounds.hpp"
 #include "Acts/Material/IMaterialDecorator.hpp"
 #include "Acts/Material/IVolumeMaterial.hpp"
@@ -424,6 +425,18 @@ void TrackingVolume::closeGeometry(
                                         logger);
     }
   }
+
+  GeometryIdentifier::Value iportal = 0;
+  for (auto& portal : portals()) {
+    auto portalId = GeometryIdentifier(volumeID).setBoundary(++iportal);
+    assert(portal.isValid() && "Invalid portal encountered during closing");
+
+    portal.surface().assignGeometryId(portalId);
+  }
+
+  for (auto& volume : volumes()) {
+    volume.closeGeometry(materialDecorator, volumeMap, vol, hook, logger);
+  }
 }
 
 // Returns the boundary surfaces ordered in probability to hit them based on
@@ -641,4 +654,16 @@ TrackingVolume& TrackingVolume::addVolume(
   return *m_volumes.back();
 }
 
+TrackingVolume::PortalRange TrackingVolume::portals() const {
+  return PortalRange{m_portals};
+}
+
+TrackingVolume::MutablePortalRange TrackingVolume::portals() {
+  return MutablePortalRange{m_portals};
+}
+
+void TrackingVolume::addPortal(std::shared_ptr<Portal> portal) {
+  m_portals.push_back(std::move(portal));
+}
+
 }  // namespace Acts