feat: Add portal tagging blueprint node

Author: paulgessinger

Core/include/Acts/Geometry/BlueprintNode.hpp

@@ -33,6 +33,7 @@ class PortalShellBase;
 namespace Experimental {
 
 class MaterialDesignatorBlueprintNode;
+class PortalDesignatorBlueprintNode;
 class StaticBlueprintNode;
 class LayerBlueprintNode;
 class GeometryIdentifierBlueprintNode;
@@ -231,6 +232,16 @@ class BlueprintNode {
       const std::function<void(MaterialDesignatorBlueprintNode& material)>&
           callback = {});
 
+  /// Convenience method for creating a @ref Acts::Experimental::PortalDesignatorBlueprintNode.
+  /// @param name The name of the portal designator node. Used for debugging
+  ///             the node tree only.
+  /// @param callback An optional callback that receives the node as an argument
+  /// @return Reference to the newly created portal designator blueprint node
+  PortalDesignatorBlueprintNode& addPortalDesignator(
+      const std::string& name,
+      const std::function<void(PortalDesignatorBlueprintNode& portals)>&
+          callback = {});
+
   /// Convenience method for creating a @ref Acts::Experimental::LayerBlueprintNode.
   /// @param name The name of the layer node.
   /// @param callback An optional callback that receives the node as an argument

Core/include/Acts/Geometry/Portal.hpp

@@ -16,7 +16,9 @@
 
 #include <exception>
 #include <memory>
+#include <span>
 #include <string>
+#include <vector>
 
 namespace Acts {
 
@@ -255,6 +257,16 @@ class Portal {
   /// @return The portal surface
   RegularSurface& surface();
 
+  /// Add a string tag to this portal. Tags are used to look the portal up from
+  /// the final @ref Acts::TrackingGeometry (e.g. the portal connecting the
+  /// tracker and the calorimeter).
+  /// @param tag The tag to add
+  void addTag(std::string tag);
+
+  /// Access the tags assigned to this portal.
+  /// @return A view of the tags assigned to this portal
+  std::span<const std::string> tags() const;
+
  private:
   /// Helper to check surface equivalence without checking material status. This
   /// is needed because we allow fusing portals with surfaces that are
@@ -272,6 +284,8 @@ class Portal {
 
   std::unique_ptr<PortalLinkBase> m_alongNormal;
   std::unique_ptr<PortalLinkBase> m_oppositeNormal;
+
+  std::vector<std::string> m_tags;
 };
 
 }  // namespace Acts

Core/include/Acts/Geometry/PortalDesignatorBlueprintNode.hpp

@@ -0,0 +1,111 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 CERN for the benefit of the ACTS project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Geometry/BlueprintNode.hpp"
+#include "Acts/Geometry/CuboidVolumeBounds.hpp"
+#include "Acts/Geometry/CylinderVolumeBounds.hpp"
+
+namespace Acts {
+
+namespace Experimental {
+
+namespace detail {
+class PortalDesignatorBlueprintNodeImpl;
+}
+
+/// This node type assigns string tags to specific portal faces of its child
+/// volume during the blueprint construction. The tags can be used to look up
+/// the corresponding portals from the final @ref Acts::TrackingGeometry, e.g.
+/// "the portal connecting the tracker and the calorimeter".
+///
+/// Tagging happens in the *finalize* phase, after all portal merging and
+/// fusing has completed, so the tagged portal is the final, shared portal that
+/// ends up in the geometry. The position of this node in the blueprint tree
+/// determines which face is meant, which makes the lookup robust against volume
+/// subdivision and portal ordering.
+/// @note This node can only have a single child. This is not an error during
+///       tree building, but during geometry construction.
+class PortalDesignatorBlueprintNode final : public BlueprintNode {
+ public:
+  /// Main constructor for the portal designator node.
+  /// @param name The name of the node (for debug only)
+  explicit PortalDesignatorBlueprintNode(const std::string& name);
+
+  ~PortalDesignatorBlueprintNode() override;
+
+  /// @copydoc BlueprintNode::name
+  const std::string& name() const override;
+
+  /// @copydoc BlueprintNode::toStream
+  void toStream(std::ostream& os) const override;
+
+  /// This method participates in the geometry construction.
+  /// It checks that this node only has a single child and forwards the call.
+  /// @param options The global blueprint options
+  /// @param gctx The geometry context (nominal usually)
+  /// @param logger The logger to use
+  /// @return The child volume
+  Volume& build(const BlueprintOptions& options, const GeometryContext& gctx,
+                const Logger& logger = Acts::getDummyLogger()) override;
+
+  /// This method participates in the geometry construction.
+  /// It captures the populated portal shell from its only child so the tags can
+  /// be applied in the finalize phase (after all merging/fusing), and forwards
+  /// the call.
+  /// @param options The global blueprint options
+  /// @param gctx The geometry context (nominal usually)
+  /// @param logger The logger to use
+  /// @return The portal shell of the child
+  PortalShellBase& connect(
+      const BlueprintOptions& options, const GeometryContext& gctx,
+      const Logger& logger = Acts::getDummyLogger()) override;
+
+  /// This method participates in the geometry construction.
+  /// It applies the configured tags to the (now final) portals of the captured
+  /// shell, then passes the call through to its only child.
+  /// @param options The global blueprint options
+  /// @param gctx The geometry context (nominal usually)
+  /// @param parent The parent volume
+  /// @param logger The logger to use during construction
+  void finalize(const BlueprintOptions& options, const GeometryContext& gctx,
+                TrackingVolume& parent, const Logger& logger) override;
+
+  /// Tag a cylinder face with a string label.
+  /// @note This method can be called multiple times to tag different faces.
+  /// @param face The face of the cylinder to tag
+  /// @param label The tag to assign to the portal at that face
+  /// @return The portal designator node
+  /// @note If this node has previously been configured with a different volume
+  ///       shape, this will throw an exception during geometry construction.
+  PortalDesignatorBlueprintNode& tagFace(CylinderVolumeBounds::Face face,
+                                         const std::string& label);
+
+  /// Tag a cuboid face with a string label.
+  /// @note This method can be called multiple times to tag different faces.
+  /// @param face The face of the cuboid to tag
+  /// @param label The tag to assign to the portal at that face
+  /// @return The portal designator node
+  /// @note If this node has previously been configured with a different volume
+  ///       shape, this will throw an exception during geometry construction.
+  PortalDesignatorBlueprintNode& tagFace(CuboidVolumeBounds::Face face,
+                                         const std::string& label);
+
+ private:
+  /// @copydoc BlueprintNode::addToGraphviz
+  void addToGraphviz(std::ostream& os) const override;
+
+  detail::PortalDesignatorBlueprintNodeImpl& impl();
+  const detail::PortalDesignatorBlueprintNodeImpl& impl() const;
+
+  std::unique_ptr<detail::PortalDesignatorBlueprintNodeImpl> m_impl;
+};
+
+}  // namespace Experimental
+}  // namespace Acts

Core/include/Acts/Geometry/TrackingGeometry.hpp

@@ -18,13 +18,16 @@
 #include "Acts/Utilities/Logger.hpp"
 
 #include <memory>
+#include <string>
+#include <string_view>
 #include <unordered_map>
 #include <utility>
 
 namespace Acts {
 
 class Layer;
 class Surface;
+class Portal;
 class PerigeeSurface;
 class IMaterialDecorator;
 class TrackingVolume;
@@ -190,6 +193,14 @@ class TrackingGeometry {
   /// @retval pointer to the found surface otherwise.
   const Surface* findSurface(GeometryIdentifier id) const;
 
+  /// Search for a portal that was tagged with the given label during the
+  /// blueprint construction (see @ref Acts::Experimental::PortalDesignatorBlueprintNode).
+  ///
+  /// @param tag the tag assigned to the portal
+  /// @retval nullptr if no portal carries the tag
+  /// @retval pointer to the tagged portal otherwise.
+  const Portal* findPortal(std::string_view tag) const;
+
   /// Access to the GeometryIdentifier - Surface association map
   /// @return Const reference to the geometry ID to surface map
   const std::unordered_map<GeometryIdentifier, const Surface*>&
@@ -219,6 +230,7 @@ class TrackingGeometry {
   // lookup containers
   std::unordered_map<GeometryIdentifier, const TrackingVolume*> m_volumesById;
   std::unordered_map<GeometryIdentifier, const Surface*> m_surfacesById;
+  std::unordered_map<std::string, const Portal*> m_portalsByTag;
 };
 
 }  // namespace Acts

Core/src/Geometry/BlueprintNode.cpp

@@ -13,6 +13,7 @@
 #include "Acts/Geometry/GeometryIdentifierBlueprintNode.hpp"
 #include "Acts/Geometry/LayerBlueprintNode.hpp"
 #include "Acts/Geometry/MaterialDesignatorBlueprintNode.hpp"
+#include "Acts/Geometry/PortalDesignatorBlueprintNode.hpp"
 #include "Acts/Geometry/StaticBlueprintNode.hpp"
 #include "Acts/Navigation/INavigationPolicy.hpp"
 #include "Acts/Navigation/TryAllNavigationPolicy.hpp"
@@ -149,6 +150,18 @@ MaterialDesignatorBlueprintNode& BlueprintNode::addMaterial(
   return *material;
 }
 
+PortalDesignatorBlueprintNode& BlueprintNode::addPortalDesignator(
+    const std::string& name,
+    const std::function<void(PortalDesignatorBlueprintNode& portals)>&
+        callback) {
+  auto portals = std::make_shared<PortalDesignatorBlueprintNode>(name);
+  addChild(portals);
+  if (callback) {
+    callback(*portals);
+  }
+  return *portals;
+}
+
 LayerBlueprintNode& BlueprintNode::addLayer(
     const std::string& name,
     const std::function<void(LayerBlueprintNode& layer)>& callback) {

Core/src/Geometry/CMakeLists.txt

@@ -56,6 +56,7 @@ target_sources(
         LayerBlueprintNode.cpp
         IndexGrid.cpp
         MaterialDesignatorBlueprintNode.cpp
+        PortalDesignatorBlueprintNode.cpp
         VolumeAttachmentStrategy.cpp
         VolumeResizeStrategy.cpp
         GeometryIdentifierBlueprintNode.cpp

Core/src/Geometry/Portal.cpp

@@ -19,6 +19,7 @@
 #include "Acts/Surfaces/RegularSurface.hpp"
 #include "Acts/Utilities/Zip.hpp"
 
+#include <algorithm>
 #include <cstdlib>
 #include <memory>
 #include <sstream>
@@ -184,6 +185,21 @@ RegularSurface& Portal::surface() {
   return *m_surface;
 }
 
+void Portal::addTag(std::string tag) {
+  if (std::ranges::find(m_tags, tag) != m_tags.end()) {
+    throw std::invalid_argument("Portal already has tag: " + tag);
+  }
+  m_tags.push_back(std::move(tag));
+}
+
+std::span<const std::string> Portal::tags() const {
+  return m_tags;
+}
+
+// Note: tags are intentionally *not* propagated through merge/fuse. These
+// operations build new portals, and portal tagging is a post-stacking operation
+// (applied in the finalize phase of the blueprint construction, after all
+// merging and fusing has happened), so there is nothing to carry over here.
 Portal Portal::merge(const GeometryContext& gctx, Portal& aPortal,
                      Portal& bPortal, AxisDirection direction,
                      const Logger& logger,