GlobalPatternFinder.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
*/
#ifndef MUONR4_FASTRECONSTRUCTIONALGS_GLOBALPATTERNFINDER__H
#define MUONR4_FASTRECONSTRUCTIONALGS_GLOBALPATTERNFINDER__H
 
#include "MuonFastRecoEvent/GlobalPattern.h"
#include "MuonRecToolInterfacesR4/IFastRecoVisualizationTool.h"
#include "MuonSpacePoint/SpacePointContainer.h"
#include "MuonSpacePoint/SpacePointPerLayerSorter.h"
#include "MuonStationIndex/MuonStationIndex.h"
#include "MuonIdHelpers/IMuonIdHelperSvc.h"
 
#include "Acts/Utilities/KDTree.hpp"
 
 
namespace MuonR4::FastReco{
    
 
    class GlobalPatternFinder : public AthMessaging {
        public:
            using StIndex = Muon::MuonStationIndex::StIndex;
            using LayerIndex = Muon::MuonStationIndex::LayerIndex;
            using SpacePointContainerVec = std::vector<const SpacePointContainer*>;
            using PatternVec = std::vector<GlobalPattern>;
            using BucketPerContainer = std::unordered_map<const SpacePointContainer*, std::vector<const SpacePointBucket*>>;
            using PatternHitVisualInfo = MuonValR4::IFastRecoVisualizationTool::PatternHitVisualInfo;
            using PatternHitVisualInfoVec = std::vector<PatternHitVisualInfo>;
           
            struct Config {
                double thetaSearchWindow {0.033};
                unsigned int maxMissedLayerHits {2};
                double baseRWindow {25};
                double minZDiff4Line {10};
                double minRDiff4Line {40};
                double phiTolerance {0.1};
                unsigned int minBendingTriggerHits {3};
                unsigned int minBendingPrecisionHits {0};
                bool useMdtHits {true};
                bool seedFromMdt {false};
                unsigned int maxSeedAttempts {2};
                std::vector<LayerIndex> layerSeedings{LayerIndex::Middle, LayerIndex::Outer};
                const MuonValR4::IFastRecoVisualizationTool* visionTool{nullptr};
                const Muon::IMuonIdHelperSvc* idHelperSvc{nullptr};
            };

            GlobalPatternFinder(const std::string& name,
                                Config&& config);

            PatternVec findPatterns(const ActsTrk::GeometryContext& gctx,
                                    const SpacePointContainerVec& spacepoints,
                                    BucketPerContainer& outBuckets) const;
 
        private:
            struct HitPayload{
                HitPayload(const SpacePoint* hit, 
                           const SpacePointBucket* bucket,
                           const SpacePointContainer* container,
                           StIndex station,
                           unsigned layerNum,
                           double R, 
                           double Z,
                           double phi);
                HitPayload(const SpacePoint* hit, 
                           StIndex station, 
                           double phi);
                const SpacePoint* hit{nullptr};
                const SpacePointBucket* bucket{nullptr};
                const SpacePointContainer* container{nullptr};
                StIndex station{};
                unsigned layerNum{0u};
                double R{0.};
                double Z{0.};
                double phi{0.};
                bool operator==(const HitPayload& other) const;
            };

            using SearchTree_t = Acts::KDTree<2, HitPayload, double, std::array, 5>;
            using TreeNode = std::pair<SearchTree_t::coordinate_t, HitPayload>;
            enum class SeedCoords : std::uint8_t{
                eSector,
                eTheta
            };

            struct PatternState {
                PatternState(const HitPayload& seed,
                             const int sectorCoord,
                             const double seedTheta);
                PatternState() = delete;
                void addHit(const HitPayload& hit,
                            const double residual,
                            const double acceptWindow);
                void overWriteHit(const HitPayload& oldHit,
                                  const HitPayload& newHit,
                                  const double newResidual,
                                  const double newAcceptWindow);
                const HitPayload& getNthLastHit(const std::size_t n) const;
                bool isInPattern(const HitPayload& hit) const;
                void finalizePatternEta();
                void finalizePatternPhi();
                bool operator==(const PatternState& other) const;
                std::unordered_map<StIndex, std::vector<HitPayload>> hitsPerStation{};
                std::vector<StIndex> stations{};
                BucketPerContainer bucketsPerContainer{};
                int sectorCoord{-1};
                int sector1{0};
                int sector2{0};
                double theta{0.};
                double phi{0.};
                unsigned nPrecisionHits{0};
                unsigned nBendingTriggerHits{0};
                unsigned nPhiHits{0};
                double meanNormResidual2{0.};
                double lastResidual{0.};
                double lastAccepWindow{0.};
                bool isOverlap{false};
                unsigned nInsertedHits{0};
                unsigned nMissedLayerHits{0};        
                Acts::CloneablePtr<PatternHitVisualInfo> visualInfo{nullptr};
                void print(std::ostream& ostr) const;
                friend std::ostream& operator<<(std::ostream& ostr, const PatternState& candidate) {
                    candidate.print(ostr);
                    return ostr;
                }
            };
            using PatternStateVec = std::vector<PatternState>;
 
            
            SearchTree_t constructTree(const ActsTrk::GeometryContext& gctx,
                                       const SpacePointContainerVec& spacepoints) const;
            PatternStateVec findPatternsInEta(const SearchTree_t& orderedSpacepoints,
                                              PatternHitVisualInfoVec* visualInfo = nullptr) const;
            void extendPatterns(PatternStateVec& activePatterns,
                                const HitPayload& test,
                                const HitPayload& seed,
                                const HitPayload& prevCandidate,
                                PatternHitVisualInfoVec* visualInfo = nullptr) const;        
            enum class CompatibilityResult : std::int8_t{
                eAddHit = 0,
                eBranchPattern = 1,
                eRejectHit = -1,
            };

            struct LineCompatibilityResult {
                CompatibilityResult result;
                double residual;
                double acceptanceWindow;
            };

            LineCompatibilityResult checkLineCompatibility(const HitPayload& seed,
                                                           const HitPayload& test,
                                                           const PatternState& pattern) const;                     
            double computeLineSlope(const HitPayload& lastPatHit,
                                    const HitPayload& seed,
                                    const bool useSeed2Beamspot,
                                    const Amg::Vector3D& beamSpot) const;
            double computeResidual(const HitPayload& testHit,
                                   const HitPayload& seed,
                                   const double lineSlope) const;
            double computeAcceptanceWindow(const HitPayload& testHit,
                                           const HitPayload& seed,
                                           const HitPayload& lastPatHit,
                                           const double lineSlope,
                                           const bool useSeed2Beamspot,
                                           const Amg::Vector3D& beamSpot) const;         
            PatternStateVec resolveOverlaps(PatternStateVec&& toResolve,
                                            PatternHitVisualInfoVec* visualInfo = nullptr) const;
            void addPhiOnlyHits(const ActsTrk::GeometryContext& gctx,
                                PatternStateVec& patterns) const;
            bool isPhiCompatible(const double testPhi,
                                 const PatternState& pattern) const;
            GlobalPattern convertToPattern(const PatternState& candidate) const;
            PatternVec convertToPattern(const PatternStateVec& candidates) const;
            enum class LayerOrdering : std::int8_t{
                eSameLayer,
                eLowerLayer,
                eHigherLayer
            };

            LayerOrdering checkLayerOrdering(const HitPayload& hit1,
                                             const HitPayload& hit2) const;
            void addVisualInfo(const PatternState& candidate, 
                               PatternHitVisualInfo::PatternStatus status,
                               PatternHitVisualInfoVec* visualInfo) const;

            SpacePointPerLayerSorter m_spSorter{};
            Config m_cfg;
    };
}
 
 
#endif