Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2026-11-18 09:56:22

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008 
0009 #pragma once
0010 
0011 #include "Acts/Definitions/Units.hpp"
0012 #include "Acts/EventData/SeedContainer.hpp"
0013 #include "Acts/EventData/SpacePointContainer.hpp"
0014 #include "Acts/Seeding/GbtsGeometry.hpp"
0015 #include "Acts/Seeding/GbtsLayerDescription.hpp"
0016 #include "Acts/Seeding/GbtsNodeStorage.hpp"
0017 #include "Acts/Seeding/GbtsRoiDescriptor.hpp"
0018 #include "Acts/Seeding/GbtsTrackingFilter.hpp"
0019 #include "Acts/Seeding/detail/GbtsGraphTypes.hpp"
0020 #include "Acts/Utilities/Logger.hpp"
0021 
0022 #include <array>
0023 #include <cstdint>
0024 #include <limits>
0025 #include <memory>
0026 #include <utility>
0027 #include <vector>
0028 
0029 namespace Acts::Experimental {
0030 
0031 /// Seed finder implementing the GBTS seeding workflow.
0032 class GraphBasedTrackSeeder {
0033  public:
0034   /// Configuration struct for the GBTS seeding algorithm.
0035   struct Config {
0036     /// Enable beam spot correction.
0037     bool beamSpotCorrection = false;
0038 
0039     /// Accepted tau range per cluster width bin, needed by the cluster width
0040     /// cuts and ignored without them.
0041     detail::GbtsTauLookupTable tauLookupTable;
0042 
0043     /// Take the strip-to-strip layer connections from the connector file
0044     /// instead of the pixel-to-pixel ones. Read where the file is loaded, not
0045     /// by the seeder itself.
0046     bool useStripConnections = false;
0047     /// Enable the cluster width cuts: wide endcap rejection and tau narrowing.
0048     bool useClusterWidthCuts = false;
0049     /// Match seeds before creating them.
0050     bool matchBeforeCreate = false;
0051     /// Bound the curvature by the pT the triplet has to reach in the actual
0052     /// field, times `oldTuningsCurvature*Fraction`, instead of the tuned
0053     /// `maxCurvature*Eta` constants.
0054     bool useOldTuningsCurvature = false;
0055     /// Open the phi window as `minDeltaPhi` plus a fraction of that same
0056     /// curvature bound, instead of the two-slope `phiWindow*` model.
0057     bool useOldTuningsPhiWindow = false;
0058     /// optional validation for barrel triplets
0059     bool validateTriplets = true;
0060     /// widens allowed variation in tau ratio
0061     /// if layer is missed in edge connecting
0062     bool useAdaptiveCuts = true;
0063     /// optionally add 3 sp seeds within a certain eta range
0064     ///
0065     /// @note Worth little until `maxAbsEtaAddTriplets` is opened past
0066     ///       `edgeMaskMinEta`; matters most where there are few layers.
0067     bool addTriplets = false;
0068     /// Tau ratio cut threshold.
0069     float tauRatioCut = 0.007;
0070     /// Tau ratio precut threshold.
0071     float tauRatioPrecut = 0.009f;
0072     /// correction applied to tau acceptance
0073     /// if a layer is missed during edge connecting
0074     float tauRatioCorr = 0.006;
0075     /// The same for a triplet any of whose three nodes a strip module made,
0076     /// whose two doublets resolved the shared node's along-strip coordinate
0077     /// separately. Reaches nothing without a strip in the triplet.
0078     float tauRatioCorrStrip = 0.03f;
0079     /// the maximum allowed eta value in which
0080     /// three spacepoint seeds are passed through
0081     float maxAbsEtaAddTriplets = 1.5;
0082     /// Maximum number of phi slices.
0083     float nMaxPhiSlice = 53;  // used to calculate phi slices
0084     /// Minimum transverse momentum.
0085     float minPt = 1.0f * UnitConstants::GeV;
0086     /// Fraction of `minPt` a triplet may fall to, allowing for three-point
0087     /// pT resolution.
0088     float tripletPtFraction = 0.8f;
0089 
0090     // graph building options
0091     /// Use eta binning from geometry structure.
0092     bool useEtaBinning = true;
0093     /// Apply RZ cuts on doublets.
0094     bool doubletFilterRZ = true;
0095     /// Maximum number of Gbts edges/doublets.
0096     std::uint32_t nMaxEdges = 2000000;
0097     /// Minimum delta radius between layers.
0098     float minDeltaRadius = 2.0 * Acts::UnitConstants::mm;
0099     /// Largest |cot(theta)| accepted for a doublet. The default corresponds to
0100     /// |eta| of about 4.3, beyond the acceptance of any current tracker.
0101     float maxAbsTau = 36.0f;
0102     /// Maximum d0 impact parameter when validating edge connection triplet
0103     float d0Max = 3.0 * UnitConstants::mm;
0104     /// Maximum difference in allowed tangent between candidate edge connection
0105     float cutDPhiMax = 0.012f;
0106     /// Maximum allowed curvature tolerance for candidate edge connections
0107     float cutDCurvMax = 0.001f;
0108     /// Minimum z0 value. In pixel mode the value is picked from the RoI.
0109     float minZ0 = -600;
0110     /// Maximum z0 value. In pixel mode the value is picked from the RoI.
0111     float maxZ0 = 600;
0112     /// Offset of the phi window under `useOldTuningsPhiWindow`.
0113     float minDeltaPhi = 0.001f;
0114 
0115     /// pT the default cut coefficients were tuned at; they scale by
0116     /// `tuningPt / minPt`.
0117     float tuningPt = 0.9f * UnitConstants::GeV;
0118     /// Maximum |curvature| above `curvatureSplitAbsTau`, before that scaling.
0119     float maxCurvatureHighEta = 4.75e-4f / UnitConstants::mm;
0120     /// Maximum |curvature| below `curvatureSplitAbsTau`, before that scaling.
0121     float maxCurvatureLowEta = 3.75e-4f / UnitConstants::mm;
0122     /// |cot(theta)| separating the two curvature cuts, |eta| of about 2.1.
0123     float curvatureSplitAbsTau = 4.0f;
0124     /// Squared fraction of the pT-derived curvature bound cut at above
0125     /// `curvatureSplitAbsTau`, under `useOldTuningsCurvature`. Large radius
0126     /// tracking cuts at the bound itself, so 1.
0127     float oldTuningsCurvatureHighEtaFraction = 0.8f;
0128     /// Squared fraction of the same below `curvatureSplitAbsTau`.
0129     float oldTuningsCurvatureLowEtaFraction = 0.6f;
0130     /// Fraction of the same the phi window opens by, per unit of radial
0131     /// separation, under `useOldTuningsPhiWindow`.
0132     float oldTuningsPhiWindowFraction = 0.68f;
0133     /// Radial separation splitting the two phi window slopes below.
0134     float phiWindowSplitDeltaRadius = 60.0f * UnitConstants::mm;
0135     /// Phi window below `phiWindowSplitDeltaRadius`, as offset plus slope times
0136     /// the radial separation.
0137     float phiWindowNearOffset = 0.002f;
0138     /// Slope of the near phi window, per unit radial separation. Scaled by
0139     /// `tuningPt / minPt`.
0140     float phiWindowNearSlope = 4.33e-4f / UnitConstants::mm;
0141     /// Phi window above `phiWindowSplitDeltaRadius`, in the same form.
0142     float phiWindowFarOffset = 0.015f;
0143     /// Slope of the far phi window, per unit radial separation. Scaled by
0144     /// `tuningPt / minPt`.
0145     float phiWindowFarSlope = 2.2e-4f / UnitConstants::mm;
0146     /// Incoming edge count below which a node is accepted without a tau match.
0147     std::uint32_t matchBeforeCreateMaxEdges = 2;
0148     /// Layers whose nodes are cut against the z0 histogram of their outer
0149     /// neighbourhood, and whose isolated nodes are skipped.
0150     std::vector<std::uint32_t> z0HistogramLayerIds{80000};
0151     /// Layers `matchBeforeCreate` applies to, when it is enabled.
0152     std::vector<std::uint32_t> matchBeforeCreateLayerIds{80000, 81000};
0153     /// Half-width of the z0 window a node is matched against in the histogram.
0154     float z0Resolution = 2.5f * UnitConstants::mm;
0155     /// Maximum radius of pixel detector
0156     float maxOuterRadius = 550.0f;
0157 
0158     /// Resolve a doublet's strip endpoints against its own direction before
0159     /// cutting on them. Nothing is written back; the correction is the pair's.
0160     bool calibrateStrips = true;
0161     /// How far along a strip a crossing may land and still be recovered, as a
0162     /// multiple of the strip half-length, so 1 is the strip itself. The same
0163     /// quantity as `TripletSeedFinder::Config::toleranceParam`.
0164     float maxStripLengthFraction = 1.1f;
0165 
0166     // Seed extraction options
0167     /// Maximum number of connected-component iterations.
0168     std::uint32_t ccaMaxIterations = 15;
0169     /// Chain length a seed candidate must reach: a triplet plus one
0170     /// confirmation. Large radius tracking asks for the triplet alone, so 2.
0171     std::uint32_t minSeedLevel = 3;
0172     /// Smallest seed size that is split into drop-out candidates.
0173     std::uint32_t minSplitSeedSize = 4;
0174     /// Largest seed size that is split.
0175     std::uint32_t maxSplitSeedSize = 5;
0176     /// Minimum eta for edge masking.
0177     float edgeMaskMinEta = 1.5;
0178     /// Threshold for hit sharing between seeds.
0179     float hitShareThreshold = 0.49;
0180     /// Max seed eta value considered for splitting.
0181     float maxSeedSplitEta = 0.6;
0182     /// Max allowed curvature for seed self consistency check.
0183     float maxInvRadDiff = 0.7e-2 / UnitConstants::m;
0184     // GbtsNodeStorage options
0185     /// Maximum endcap cluster width.
0186     float maxEndcapClusterWidth = 0.35f * Acts::UnitConstants::mm;
0187     /// Half-length in local y of a pixel module, against which the distance of
0188     /// a cluster to the module edge is measured.
0189     float moduleHalfLengthY = 10.0f * Acts::UnitConstants::mm;
0190     /// Distance to the module edge below which a cluster may be shortened,
0191     /// which switches to the tau lookup table's near-edge bounds.
0192     float moduleEdgeTolerance = 0.3f * Acts::UnitConstants::mm;
0193     /// Cluster width covered by one bin of the tau lookup table.
0194     float tauLutBinWidth = 0.05f * Acts::UnitConstants::mm;
0195     /// Multiples of the phi slice width duplicated either side of the
0196     /// wrap-around, so a sliding window never has to wrap.
0197     float phiIndexMargin = 1.5f;
0198     /// Buckets used to sort an eta bin by phi, at most
0199     /// `GbtsNodeStorage::kMaxPhiSortBuckets`.
0200     std::uint32_t phiSortBuckets = 31;
0201   };
0202 
0203   /// Derived configuration struct that contains calculated parameters based on
0204   /// the configuration.
0205   struct DerivedConfig : public Config {
0206     /// Construct derived configuration from base configuration.
0207     /// @param config Base configuration to derive from
0208     explicit DerivedConfig(const Config& config);
0209 
0210     /// Phi slice width
0211     float phiSliceWidth = std::numeric_limits<float>::quiet_NaN();
0212   };
0213 
0214   /// Optional inputs for variables passed in
0215   /// or derived during runtime.
0216   struct Options {
0217     /// @param bFieldInZ_ the magnetic field in z
0218     explicit Options(float bFieldInZ_);
0219 
0220     /// Magnetic field in z
0221     /// units of GeV/(e*mm).
0222     float bFieldInZ{};
0223 
0224     /// Transverse momentum coefficient (~0.3*B/2 - assumes nominal field of
0225     /// 2*T).
0226     double ptCoeff{};
0227   };
0228 
0229   /// @param config Configuration for the seed finder
0230   /// @param geometry GBTS geometry
0231   /// @param logger Logging instance
0232   GraphBasedTrackSeeder(const DerivedConfig& config,
0233                         std::shared_ptr<GbtsGeometry> geometry,
0234                         std::unique_ptr<const Acts::Logger> logger =
0235                             Acts::getDefaultLogger("Finder",
0236                                                    Acts::Logging::Level::INFO));
0237 
0238   /// Create an empty node storage matching this seeder's configuration.
0239   ///
0240   /// Fill it through GbtsNodeStorage::insert, then call
0241   /// GbtsNodeStorage::finalize before handing it to createSeeds.
0242   /// @return An empty node storage
0243   GbtsNodeStorage makeNodeStorage() const;
0244 
0245   /// Create seeds from an ACTS space point container in a region of interest.
0246   ///
0247   /// Convenience wrapper that builds and finalizes the node storage itself. The
0248   /// container must carry the `layerId`, `clusterWidth` and `localPositionY`
0249   /// columns.
0250   /// @param spacePoints Space point container
0251   /// @param roi Region of interest descriptor
0252   /// @param filter Tracking filter to be applied
0253   /// @param options Event based options such as magnetic field strength
0254   /// @param outputSeeds Container with generated seeds
0255   void createSeeds(const SpacePointContainer& spacePoints,
0256                    const GbtsRoiDescriptor& roi,
0257                    const GbtsTrackingFilter& filter, const Options& options,
0258                    SeedContainer& outputSeeds) const;
0259 
0260   /// Create seeds from a finalized node storage in a region of interest.
0261   /// @param nodeStorage Finalized graph node storage
0262   /// @param roi Region of interest descriptor
0263   /// @param filter Tracking filter to be applied
0264   /// @param options Event based options such as magnetic field strength
0265   /// @param outputSeeds Container with generated seeds
0266   void createSeeds(GbtsNodeStorage& nodeStorage, const GbtsRoiDescriptor& roi,
0267                    const GbtsTrackingFilter& filter, const Options& options,
0268                    SeedContainer& outputSeeds) const;
0269 
0270  private:
0271   /// candidate seed metadata produced by the GBTS algorithm.
0272   struct SeedCandidateProperties {
0273     /// @param quality Seed quality score
0274     /// @param clone Clone flag
0275     /// @param sps Vector of graph node indices
0276     /// @param splitFlag used to flag if seed needs to be split in two
0277     SeedCandidateProperties(float quality, std::int32_t clone,
0278                             std::vector<SpacePointIndex> sps,
0279                             std::uint32_t splitFlag)
0280         : seedQuality(quality),
0281           isClone(clone),
0282           nodes(std::move(sps)),
0283           forSeedSplitting(splitFlag) {}
0284 
0285     /// Seed quality score.
0286     float seedQuality{};
0287     /// Clone flag.
0288     std::int32_t isClone{};
0289     /// Graph node indices.
0290     std::vector<SpacePointIndex> nodes;
0291     /// Flag for seed splitting.
0292     std::uint32_t forSeedSplitting{};
0293   };
0294 
0295   /// Output seed metadata
0296   struct OutputSeedProperties {
0297     /// @param quality Seed quality score
0298     /// @param sps Vector of space point indices in the seed
0299     OutputSeedProperties(float quality, std::vector<std::uint32_t> sps)
0300         : seedQuality(quality), spacePoints(std::move(sps)) {}
0301 
0302     /// Quality of seed.
0303     float seedQuality{};
0304     /// Index of spacepoints in seed.
0305     std::vector<std::uint32_t> spacePoints;
0306   };
0307 
0308   /// Sliding window in phi used to define range used for edge creation.
0309   ///
0310   /// Covers one non-empty source eta bin, whose phi-ordered node list it holds
0311   /// directly so that the innermost loop does not reach through the bin.
0312   struct SlidingWindow {
0313     /// phi-ordered nodes of the bin, including the wrap-around duplicates
0314     const std::pair<float, SpacePointIndex>* phiNodes{};
0315     /// number of entries in @c phiNodes
0316     std::uint32_t numPhiNodes{};
0317     /// sliding window position
0318     std::uint32_t firstIt{};
0319     /// window half-width;
0320     float deltaPhi{};
0321     /// GBTS layer ID of the bin
0322     std::uint32_t layerId{};
0323     /// Type of the bin's layer.
0324     GbtsLayerType type{};
0325     /// Technology of the bin's layer.
0326     GbtsLayerTechnology technology{};
0327   };
0328   DerivedConfig m_cfg;
0329 
0330   std::shared_ptr<const GbtsGeometry> m_geometry;
0331 
0332   std::unique_ptr<const Acts::Logger> m_logger =
0333       Acts::getDefaultLogger("Finder", Acts::Logging::Level::INFO);
0334 
0335   const Acts::Logger& logger() const { return *m_logger; }
0336 
0337   /// Build doublet graph from nodes.
0338   /// @param roi Region of interest descriptor
0339   /// @param nodeStorage Data storage containing nodes
0340   /// @param edgeStorage Storage for generated edges
0341   /// @param options Event based options such as magnetic field strength
0342   /// @return Pair of edge count and maximum level
0343   std::pair<std::int32_t, std::int32_t> buildTheGraph(
0344       const GbtsRoiDescriptor& roi, GbtsNodeStorage& nodeStorage,
0345       std::vector<detail::GbtsEdge>& edgeStorage, const Options& options) const;
0346 
0347   /// Run connected component analysis on the graph.
0348   /// @param nEdges Number of edges in the graph
0349   /// @param edgeStorage Storage containing graph edges
0350   /// @return Number of connected components found
0351   std::int32_t runCCA(std::uint32_t nEdges,
0352                       std::vector<detail::GbtsEdge>& edgeStorage) const;
0353 
0354   /// Extract seed candidates from the graph.
0355   /// @param maxLevel Maximum level in the graph
0356   /// @param nEdges Number of edges
0357   /// @param nodeStorage Storage containing the graph nodes
0358   /// @param edgeStorage Storage containing edges
0359   /// @param vOutputSeeds Output vector for seed candidates
0360   /// @param filter Tracking filter to be applied
0361   void extractSeedsFromTheGraph(std::uint32_t maxLevel, std::uint32_t nEdges,
0362                                 const GbtsNodeStorage& nodeStorage,
0363                                 std::vector<detail::GbtsEdge>& edgeStorage,
0364                                 std::vector<OutputSeedProperties>& vOutputSeeds,
0365                                 const GbtsTrackingFilter& filter) const;
0366 
0367   /// Check to see if z0 of segment is within the expected z range of the
0368   /// beamspot
0369   /// @param z0BitMask Sets allowed bins of allowed z value
0370   /// @param z0 Estimated z0 of segments z value at beamspot
0371   /// @param z0HistoCoeff Scalfactor that converts z coodindate into bin index
0372   /// @return Whether segment is within beamspot range
0373   bool checkZ0BitMask(std::uint16_t z0BitMask, float z0,
0374                       float z0HistoCoeff) const;
0375 
0376   /// Estimate the inverse radius of the circle through three nodes.
0377   /// @param nodeView View of the node positions and layers
0378   /// @param nodes The three graph nodes, innermost first
0379   /// @return The estimated inverse radius
0380   float estimateCurvature(const detail::GbtsNodeView& nodeView,
0381                           const std::array<SpacePointIndex, 3>& nodes) const;
0382 
0383   /// Check a triplet against the pT and d0 cuts.
0384   /// @param nodeView View of the node positions and layers
0385   /// @param candidateTriplet The three graph nodes
0386   /// @param tripletMinPt Minimum transverse momentum
0387   /// @param tauRatio Tau ratio of the triplet
0388   /// @param tauRatioCut Tau ratio cut threshold
0389   /// @param options Event based options such as magnetic field strength
0390   /// @return Whether the triplet is accepted
0391   bool validateTriplet(const detail::GbtsNodeView& nodeView,
0392                        const std::array<SpacePointIndex, 3>& candidateTriplet,
0393                        float tripletMinPt, float tauRatio, float tauRatioCut,
0394                        const Options& options) const;
0395 };
0396 
0397 }  // namespace Acts::Experimental