EIC code displayed by LXR master/​acts/​Core/​include/​Acts/​Geometry/​SurfaceArrayCreator.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-09-24 08:17:44

 // 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/Definitions/Algebra.hpp"
 #include "Acts/Definitions/Units.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
 #include "Acts/Geometry/ProtoLayer.hpp"
 #include "Acts/Surfaces/Surface.hpp"
 #include "Acts/Surfaces/SurfaceArray.hpp"
 #include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/BinningType.hpp"
 #include "Acts/Utilities/IAxis.hpp"
 #include "Acts/Utilities/Logger.hpp"
 
 #include <cmath>
 #include <cstddef>
 #include <functional>
 #include <memory>
 #include <numbers>
 #include <optional>
 #include <utility>
 #include <vector>
 
 namespace ActsTests {
 struct SurfaceArrayCreatorFixture;
 }
 
 namespace Acts {
 
 /// Function type for comparing two surfaces in a given geometry context and
 /// axis direction.
 /// @param gctx The geometry context for the comparison
 /// @param dir The axis direction to consider
 /// @param s1 First surface to compare
 /// @param s2 Second surface to compare
 /// @return True if the surfaces are considered equivalent for binning purposes
 using SurfaceMatcher =
     std::function<bool(const GeometryContext& gctx, AxisDirection,
                        const Surface*, const Surface*)>;
 
 /// Vector of pointers to constant Surface objects
 using SurfaceVector = std::vector<const Surface*>;
 /// Matrix (2D vector) of pointers to constant Surface objects
 using SurfaceMatrix = std::vector<SurfaceVector>;
 
 /// @typedef V3Vector
 /// Vector of 3D vectors, used for storing collections of 3D points.
 using V3Vector = std::vector<Vector3>;
 
 /// @typedef V3Matrix
 /// Matrix (2D vector) of 3D vectors, used for storing grid-like collections of
 /// 3D points.
 using V3Matrix = std::vector<V3Vector>;
 
 /// @class SurfaceArrayCreator
 ///
 /// It is designed create sub surface arrays to be ordered on Surfaces
 ///
 /// @todo write more documentation on how this is done
 class SurfaceArrayCreator {
  public:
   friend struct ActsTests::SurfaceArrayCreatorFixture;
 
   /// Configuration options for the surface array creator.
   struct Config {
     /// Type-erased function which determines whether two surfaces are
     /// supposed to be considered equivalent in terms of the binning
     SurfaceMatcher surfaceMatcher = SurfaceArrayCreator::isSurfaceEquivalent;
 
     /// Optimize the binning in phi for disc layers. Reduces the number
     /// of bins to the lowest number of non-equivalent phi surfaces
     /// of all r-bins. If false, this step is skipped.
     bool doPhiBinningOptimization = true;
   };
 
   /// Constructor with default config
   ///
   /// @param logger logging instance
   explicit SurfaceArrayCreator(std::unique_ptr<const Logger> logger =
                                    getDefaultLogger("SurfaceArrayCreator",
                                                     Logging::INFO))
       : m_cfg(Config()), m_logger(std::move(logger)) {}
   /// Constructor with explicit config
   ///
   /// @param cfg Explicit config struct
   /// @param logger logging instance
   explicit SurfaceArrayCreator(const Config& cfg,
                                std::unique_ptr<const Logger> logger =
                                    getDefaultLogger("SurfaceArrayCreator",
                                                     Logging::INFO))
       : m_cfg(cfg), m_logger(std::move(logger)) {}
 
   /// Destructor
   virtual ~SurfaceArrayCreator() = default;
 
   /// SurfaceArrayCreator interface method
   ///
   /// - create an array in a cylinder, binned in phi, z when extrema and
   /// bin numbers are known
   /// @warning This function requires the cylinder aligned with the z-axis
   /// @param surfaces is the vector of pointers to sensitive surfaces
   /// to be ordered on the cylinder
   /// @pre the pointers to the sensitive surfaces in the surfaces vectors all
   /// need to be valid, since no check is performed
   /// @param [in] gctx The geometry context for this building call
   /// @param protoLayerOpt The proto layer containing the layer size
   /// @param binsPhi is the number of bins in phi for the surfaces
   /// @param binsZ is the number of bin in Z for the surfaces
   /// @param transform is the (optional) additional transform applied
   /// @param neighborWindow Bounds on the neighbor window the lookup derives
   ///        from the crossing angle, in bins per grid axis (phi, z)
   /// @param overfill Extra cells per direction and axis to fill around each matched cell
   ///
   /// @return a unique pointer to a new SurfaceArray
   SurfaceArray surfaceArrayOnCylinder(
       const GeometryContext& gctx,
       std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t binsPhi,
       std::size_t binsZ, std::optional<ProtoLayer> protoLayerOpt = std::nullopt,
       const Transform3& transform = Transform3::Identity(),
       SurfaceArray::NeighborWindow neighborWindow = {{0, 0}, {1, 2}},
       std::uint8_t overfill = 0) const;
 
   /// SurfaceArrayCreator interface method
   ///
   /// - create an array in a cylinder, binned in phi, z when extrema and bin
   /// numbers are unknown - this method goes through the surfaces and finds
   /// out the needed information
   /// @warning This function requires the cylinder aligned with the z-axis
   /// @param surfaces is the vector of pointers to sensitive surfaces
   /// to be ordered on the cylinder
   /// @pre the pointers to the sensitive surfaces in the surfaces vectors all
   /// need to be valid, since no check is performed
   /// @param [in] gctx The geometry context for this building call
   /// @param protoLayerOpt The proto layer containing the layer size
   /// @param bTypePhi the binning type in phi direction (equidistant/arbitrary)
   /// @param bTypeZ the binning type in z direction (equidistant/arbitrary)
   /// @param transform is the (optional) additional transform applied
   /// @param neighborWindow Bounds on the neighbor window the lookup derives
   ///        from the crossing angle, in bins per grid axis (phi, z)
   /// @param overfill Extra cells per direction and axis to fill around each matched cell
   ///
   /// @return a unique pointer a new SurfaceArray
   SurfaceArray surfaceArrayOnCylinder(
       const GeometryContext& gctx,
       std::vector<std::shared_ptr<const Surface>> surfaces,
       BinningType bTypePhi = equidistant, BinningType bTypeZ = equidistant,
       std::optional<ProtoLayer> protoLayerOpt = std::nullopt,
       const Transform3& transform = Transform3::Identity(),
       SurfaceArray::NeighborWindow neighborWindow = {{0, 0}, {1, 2}},
       std::uint8_t overfill = 0) const;
 
   /// SurfaceArrayCreator interface method
   /// - create an array on a disc, binned in r, phi when extrema and
   /// bin numbers are known
   ///
   /// @param surfaces is the vector of pointers to sensitive surfaces
   /// to be ordered on the disc
   /// @pre the pointers to the sensitive surfaces in the surfaces vectors all
   /// need to be valid, since no check is performed
   /// @warning This function requires the disc aligned with the z-axis
   /// @param [in] gctx The geometry context for this building call
   /// @param protoLayerOpt The proto layer containing the layer size
   /// @param binsPhi is the number of bins in phi for the surfaces
   /// @param binsR is the number of bin in R for the surfaces
   /// @param transform is the (optional) additional transform applied
   /// @param neighborWindow Bounds on the neighbor window the lookup derives
   ///        from the crossing angle, in bins per grid axis (r, phi)
   /// @param overfill Extra cells per direction and axis to fill around each matched cell
   ///
   /// @return a unique pointer a new SurfaceArray
   SurfaceArray surfaceArrayOnDisc(
       const GeometryContext& gctx,
       std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t binsR,
       std::size_t binsPhi,
       std::optional<ProtoLayer> protoLayerOpt = std::nullopt,
       const Transform3& transform = Transform3::Identity(),
       SurfaceArray::NeighborWindow neighborWindow = {{0, 0}, {2, 1}},
       std::uint8_t overfill = 0) const;
 
   /// SurfaceArrayCreator interface method
   ///
   /// - create an array in a cylinder, binned in phi, r when extrema and bin
   /// numbers are unknown - this method goes through the surfaces and finds
   /// out the needed information
   /// @param surfaces is the vector of pointers to sensitive surfaces
   /// to be ordered on the disc
   /// @pre the pointers to the sensitive surfaces in the surfaces vectors all
   /// need to be valid, since no check is performed
   /// @warning This function requires the disc aligned with the z-axis
   /// @param [in] gctx The geometry context for this building call
   /// @param protoLayerOpt The proto layer containing the layer size
   /// @param bTypeR the binning type in r direction (equidistant/arbitrary)
   /// @param bTypePhi the binning type in phi direction (equidistant/arbitrary)
   /// @param transform is the (optional) additional transform applied
   /// @param neighborWindow Bounds on the neighbor window the lookup derives
   ///        from the crossing angle, in bins per grid axis (r, phi)
   /// @param overfill Extra cells per direction and axis to fill around each matched cell
   ///
   /// @return a unique pointer a new SurfaceArray
   ///
   /// @note If there is more than on R-Ring, number of phi bins
   ///       will be set to lowest number of surfaces of any R-ring.
   ///       This ignores bTypePhi and produces equidistant binning in phi
   SurfaceArray surfaceArrayOnDisc(
       const GeometryContext& gctx,
       std::vector<std::shared_ptr<const Surface>> surfaces, BinningType bTypeR,
       BinningType bTypePhi,
       std::optional<ProtoLayer> protoLayerOpt = std::nullopt,
       const Transform3& transform = Transform3::Identity(),
       SurfaceArray::NeighborWindow neighborWindow = {{0, 0}, {2, 1}},
       std::uint8_t overfill = 0) const;
 
   /// SurfaceArrayCreator interface method
   /// - create an array on a plane
   ///
   /// @param [in] gctx The geometry context for this building call
   /// @param [in] surfaces is the vector of pointers to sensitive surfaces
   /// to be ordered on the plane
   /// @pre the pointers to the sensitive surfaces in the surfaces vectors all
   /// need to be valid, since no check is performed
   /// @warning This function requires the plane aligned with either the x-, y-
   /// or z-axis
   /// @param [in] bins1 is the number of bins in the orthogonal direction to @p
   /// aDir
   /// @param [in] bins2 is the number of bins in the orthogonal direction to @p
   /// aDir
   /// @param [in] aDir Direction of the aligned surfaces
   /// @param [in] protoLayerOpt Optional @c ProtoLayer instance
   /// @param [in] transform is the (optional) additional transform applied
   /// @param neighborWindow Bounds on the neighbor window the lookup derives
   ///        from the crossing angle, in bins per grid axis
   /// @param overfill Extra cells per direction and axis to fill around each matched cell
   ///
   /// @return a unique pointer a new SurfaceArray
   SurfaceArray surfaceArrayOnPlane(
       const GeometryContext& gctx,
       std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t bins1,
       std::size_t bins2, AxisDirection aDir,
       std::optional<ProtoLayer> protoLayerOpt = std::nullopt,
       const Transform3& transform = Transform3::Identity(),
       SurfaceArray::NeighborWindow neighborWindow = {{0, 0}, {2, 2}},
       std::uint8_t overfill = 0) const;
 
   /// Static check function for surface equivalent
   ///
   /// @param [in] gctx the geometry context for this check
   /// @param aDir the axis direction for the binning
   /// @param a first surface for checking
   /// @param b second surface for checking
   /// @return true if surfaces are equivalent for binning purposes
   static bool isSurfaceEquivalent(const GeometryContext& gctx,
                                   AxisDirection aDir, const Surface* a,
                                   const Surface* b) {
     using namespace UnitLiterals;
     using VectorHelpers::perp;
 
     if (aDir == AxisDirection::AxisPhi) {
       // Take the two binning positions
       Vector3 pos1 = a->referencePosition(gctx, AxisDirection::AxisR);
       Vector3 pos2 = b->referencePosition(gctx, AxisDirection::AxisR);
 
       // Project them on the (x, y) plane, where Phi angles are calculated
       auto proj1 = pos1.head<2>(), proj2 = pos2.head<2>();
 
       // Basic dot and cross products identities give us the cosine and sine
       // of these angles, time the squared vector norm
       auto cos_dPhi_n2 = proj1.dot(proj2);
       auto sin_dPhi_n2 = proj1.x() * proj2.y() - proj2.x() * proj1.y();
 
       // ...so by injecting them into atan2, we get the angle between them
       auto dPhi = std::atan2(sin_dPhi_n2, cos_dPhi_n2);
       return std::abs(dPhi) < std::numbers::pi / 180.;
     }
 
     if (aDir == AxisDirection::AxisZ) {
       return (std::abs(a->referencePosition(gctx, AxisDirection::AxisR).z() -
                        b->referencePosition(gctx, AxisDirection::AxisR).z()) <
               1_um);
     }
 
     if (aDir == AxisDirection::AxisR) {
       return (std::abs(perp(a->referencePosition(gctx, AxisDirection::AxisR)) -
                        perp(b->referencePosition(gctx, AxisDirection::AxisR))) <
               1_um);
     }
 
     return false;
   }
 
   /// Set logging instance
   /// @param logger is the logging instance to be set
   void setLogger(std::unique_ptr<const Logger> logger) {
     m_logger = std::move(logger);
   }
 
   /// Determine the number of bins for a binning direction from the number of
   /// distinct module positions (i.e. one bin per module). Public so navigation
   /// policies can size their surface-array grids relative to the module count.
   /// @param gctx the geometry context
   /// @param surfaces the surfaces to analyse
   /// @param aDir the binning direction
   /// @return the number of distinct module positions along @p aDir
   std::size_t determineBinCount(const GeometryContext& gctx,
                                 const std::vector<const Surface*>& surfaces,
                                 AxisDirection aDir) const;
 
  private:
   /// configuration object
   Config m_cfg;
 
   /// Private access to logger
   const Logger& logger() const { return *m_logger; }
 
   std::vector<const Surface*> findKeySurfaces(
       const std::vector<const Surface*>& surfaces,
       const std::function<bool(const Surface*, const Surface*)>& equal) const;
 
   /// SurfaceArrayCreator internal method
   /// Creates a variable axis from a vector of (unsorted) surfaces with
   /// PlanarBounds
   /// It loops through the surfaces and finds out the needed information
   /// First the surfaces are sorted in the binning direction and the so called
   /// "key" surfaces (surfaces with different positions in the binning
   /// direction) are extracted. The boundary value between two surfaces is the
   /// mean value of the two center position in the binning direction. The
   /// first and the last boundaries are calculated from the vertices of the
   /// first and last surface.
   /// @note currently implemented for phi, r and z bining
   /// @todo implement for x,y binning
   /// @param [in] gctx the geometry context for this call
   /// @param surfaces are the sensitive surfaces to be
   /// @param aBoundaryType the AxisBoundaryType for the axis to be created
   /// @param aDir the AxisDirection in which direction should be binned
   /// (currently possible: AxisPhi, AxisR, AxisZ)
   /// @param protoLayer Instance of @c ProtoLayer holding generic layer info
   /// @param transform is the (optional) additional transform applied
   /// @return Type-erased @c IAxis containing the determined properties
   std::unique_ptr<const IAxis> createVariableAxis(
       const GeometryContext& gctx, const std::vector<const Surface*>& surfaces,
       AxisBoundaryType aBoundaryType, AxisDirection aDir,
       const ProtoLayer& protoLayer, Transform3& transform) const;
 
   /// SurfaceArrayCreator internal method
   /// Creates a equidistant axis when the extrema and the bin number
   /// are known.
   /// It loops through the surfaces and finds out the needed information
   /// First the surfaces are sorted in the binning direction and the so called
   /// "key" surfaces (surfaces with different positions in the binning
   /// direction) are extracted. The number of key surfaces equals the number
   /// of bins. Afterwards the minimum and maximum are calculated by
   /// subtracting/adding half of a bin size to the center position (in the
   /// binning direction) to the first/last surface.
   /// @note currently implemented for phi, r and z bining
   /// @todo implement for x,y binning
   /// @param [in] gctx the geometry context for this call
   /// @param surfaces are the sensitive surfaces to be
   /// @param aBoundaryType the AxisBoundaryType for the axis to be created
   /// @param aDir the AxisDirection in which direction should be binned
   /// (currently possible: AxisPhi, AxisR, AxisZ)
   /// @param protoLayer Instance of @c ProtoLayer holding generic layer info
   /// @param transform is the (optional) additional transform applied
   /// @param nBins Number of bins to use, 0 means determine automatically
   /// @return Type-erased @c IAxis containing the determined properties
   std::unique_ptr<const IAxis> createEquidistantAxis(
       const GeometryContext& gctx, const std::vector<const Surface*>& surfaces,
       AxisBoundaryType aBoundaryType, AxisDirection aDir,
       const ProtoLayer& protoLayer, Transform3& transform,
       std::size_t nBins = 0) const;
 
   /// logging instance
   std::unique_ptr<const Logger> m_logger;
 
   /// Private helper method to transform the  vertices of surface bounds into
   /// global coordinates
   /// @param [in] gctx the geometry context for this call
   /// @param surface the surface associated with the given vertices
   /// @param locVertices a vector of the vertices in local coordinates
   /// @return a vector of the vertices in global coordinates
   std::vector<Vector3> makeGlobalVertices(
       const GeometryContext& gctx, const Surface& surface,
       const std::vector<Vector2>& locVertices) const;
 };
 
 }  // namespace Acts

This page was automatically generated by the 2.3.7 LXR engine. The LXR team