|
|
|||
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
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|