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 "MuonSpacePoint/SpacePointHelpers.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 {
                bool useMdtHits {true};
                bool seedFromMdt {false};
                std::vector<LayerIndex> layerSeedings{LayerIndex::Middle, LayerIndex::Outer};
                /********* Pattern bulding acceptance **********/ 
                double thetaSearchWindow {0.033};
                double baseRWindow {25};
                double phiTolerance {0.1};
                /********* Pile-up & Fake rate suppression *****/
                unsigned int minBendingTriggerHits {3};
                unsigned int minBendingPrecisionHits {0};
                unsigned int minPhiHits {1};
                double meanNormRes2Cut {0.2};
                /********* Pattern recovery power **************/
                unsigned int maxSeedAttempts {2};
                unsigned int maxMissedLayerHits {2};
                /********* Numerical stability *****************/
                double minLayerSeparation {40};
                /********* Pattern quality evaluation **********/
                double precisionWeight {0.75};
                double hitScoreSaturation {10.0};
                double residualPenalty {1.5};
                double phiBonusSaturation {4.0};
                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,
                           uint8_t layerNum,
                           double R, 
                           double Z,
                           double phi);
                HitPayload(const SpacePoint* hit, 
                           StIndex station,
                           uint8_t layerNum,
                           double phi);
                const SpacePoint* hit{nullptr};
                const SpacePointBucket* bucket{nullptr};
                const SpacePointContainer* container{nullptr};
                double R{0.};
                double Z{0.};
                double phi{0.};
                StIndex station{};
                uint8_t layerNum{0u};
                bool isPrecision{MuonR4::isPrecisionHit(*hit)};
                bool operator==(const HitPayload& other) const;
                const SpacePoint* operator->() const { return hit; }
                const SpacePoint& operator*() const { return *hit; }
            };

            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 uint8_t sectorCoord,
                             const double seedTheta);
                PatternState() = delete; 
                PatternState(PatternState&& other) noexcept = default;
                PatternState& operator=(PatternState&& other) noexcept = default;
                PatternState(const PatternState& other) = default;
                PatternState& operator=(const PatternState& other) = default;
                ~PatternState() =default;
                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 uint8_t n) const;
                bool isInPattern(const HitPayload& hit) const;
                void finalizePatternEta();
                void finalizePatternPhi();

                Acts::CloneablePtr<PatternHitVisualInfo> visualInfo{nullptr};
                const SpacePoint* lastInsertedHit{nullptr};
                const SpacePoint* prevLayerHit{nullptr};
                double theta{0.};
                double phi{0.};
                double meanNormResidual2{0.};
                double lastResidual{0.};
                double lastAcceptWindow{0.};
                uint8_t nPrecisionHits{0u};
                uint8_t nBendingTriggerHits{0u};
                uint8_t nPhiHits{0u};
                uint8_t nMissedLayerHits{0u};
                uint8_t sectorCoord{0};
                uint8_t sector1{0};
                uint8_t sector2{0};
                bool isFinalized{false};
                bool isOverlap{false};

                std::unordered_map<StIndex, std::vector<HitPayload>> hitsPerStation{};
                std::vector<StIndex> stations{};
                BucketPerContainer bucketsPerContainer{};

                bool operator==(const PatternState& other) const = delete;        
                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 {CompatibilityResult::eRejectHit};
                double residual{0.};
                double accWindow{0.};
            };

            LineCompatibilityResult checkLineCompatibility(const HitPayload& seed,
                                                           const HitPayload& test,
                                                           const PatternState& pat) const;
            LineCompatibilityResult computeResidual(const HitPayload& seed,
                                                    const HitPayload& test,
                                                    const PatternState& pat,
                                                    const uint8_t patHitIdx,
                                                    const Amg::Vector3D& beamSpot) const;
            bool isBetter(const PatternState& a, const PatternState& b) 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
            };
            using enum GlobalPatternFinder::LayerOrdering;
            static LayerOrdering checkLayerOrdering(const HitPayload& hit1,
                                                    const HitPayload& hit2);
            void addVisualInfo(const PatternState& candidate, 
                               PatternHitVisualInfo::PatternStatus status,
                               PatternHitVisualInfoVec* visualInfo) const;

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