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 "MuonTrackEvent/ExpandedSector.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.05};
                double baseResidualSigma {25};
                double phiTolerance {0.1};
                /********* Pile-up & Fake rate suppression *****/
                unsigned int minTriggerLayers {3};
                unsigned int minPrecisionLayers {0};
                unsigned int minPhiLayers {1};
                unsigned int minStationLayers {4};
                double meanNormRes2Cut {0.2};
                /********* Pattern recovery power **************/
                unsigned int maxSeedAttempts {2};
                unsigned int maxMissLayersInStation {2};
                /********* Numerical stability *****************/
                double minHitDistance4Line {40};
                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:
            static const int s_nStations{Acts::toUnderlying(StIndex::StIndexMax)};
            struct HitPayload{
                const SpacePoint* hit{nullptr};
                const SpacePointBucket* bucket{nullptr};
                const SpacePointContainer* container{nullptr};
                Amg::Vector3D position{Amg::Vector3D::Zero()};
                Amg::Vector3D sensorDir{Amg::Vector3D::Zero()};
                StIndex station{};
                uint8_t locLayer{0u};
                uint8_t sector{0u};
                bool isPrecision{false};
                bool isStraw{false};
                bool operator==(const HitPayload& other) const;
                const SpacePoint* operator->() const { return hit; }
                const SpacePoint& operator*() const { return *hit; }
                const SpacePoint* sp() const { return hit; }
            };

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

            struct CandidateHit {
                const HitPayload* hit{nullptr};
                StIndex station{};
                uint8_t globLayer{0u};
                uint8_t sector{0u};
                bool isStraw{false};
 
                // Forward commonly used accessors for convenience
                const HitPayload* operator->() const { return hit; }
                const HitPayload& operator*() const { return *hit; }
                const SpacePoint* sp() const { return hit->sp(); }
                bool operator==(const CandidateHit& other) const { return *hit == *other.hit; }
                bool operator==(const HitPayload& other) const { return *hit == other; }
                // Print and stream operator
                friend std::ostream& operator<<(std::ostream& ostr, const CandidateHit& c) {
                    c.print(ostr);
                    return ostr;
                }
                void print(std::ostream& ostr) const;
            };
        
            enum class LineTestDecision : std::int8_t{
                eAddHit,
                eBranchPattern,
                eRejectHit,
                eConsecutiveMdt,
                eOverwriteLastHit
            };

            struct LineTestRes  {
                LineTestDecision result {LineTestDecision::eRejectHit};
                double residual{0.};
                double accWindow{0.};
            };

            struct PatternState {
                PatternState(const CandidateHit& seed,
                             const std::int8_t expSector,
                             const Config* cfg,
                             const AthMessaging* logger);
                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 CandidateHit& hit,
                            const double residual,
                            const double acceptWindow);
                void overWriteHit(const CandidateHit& newHit,
                                  const double newResidual,
                                  const double newAcceptWindow);
                LineTestRes checkLineComp(const CandidateHit& testHit,
                                          const Amg::Vector3D& beamSpot);
                LineTestRes computeLineResidual(const CandidateHit& testHit) const;
                Amg::Vector3D projToPhiPlane(const HitPayload& hit) const;
                bool isPhiCompatible(const double testPhi) const;
                bool isInPattern(const HitPayload& hit) const;
                void finalizePatternPhi();
                void moveLineAnchorHit(const CandidateHit& refHit);
                void updateLineParameters(const Amg::Vector3D& beamSpot);
                void updatePatternPhi(const double newPhi);
                double getMeanResidual2() const;
                uint8_t nBendingHits() const;
                uint8_t nBendingLayers() const;
                uint8_t nStations(const bool onlyGoodStations) const;
                std::vector<const SpacePointBucket*> getParentBuckets() const;
                bool isInLastLayer(const CandidateHit& hit) const;

                const Config* cfg{nullptr};
                const AthMessaging* logger{nullptr};
                Acts::CloneablePtr<PatternHitVisualInfo> visualInfo{nullptr};
                CandidateHit lastInsertedHit{};
                CandidateHit prevLayerHit{};
                CandidateHit lineAnchorHit{};
                CandidateHit seedHit{};
                Amg::Vector3D bendPlaneNorm{Amg::Vector3D::Zero()};
                Amg::Vector3D linePos{Amg::Vector3D::Zero()};
                Amg::Vector3D lineDir{Amg::Vector3D::Zero()};
                double leverArm{0.};
                double meanNormResidual2{0.};
                double lastResidual{0.};
                double lastAcceptWindow{0.};
                double patPhi{0.};
                ExpandedSector expSect{static_cast<int8_t>(0)};
                uint8_t nPrecisionLayers{0u};
                uint8_t nTriggerLayers{0u};
                uint8_t nPhiLayers{0u};
                bool isFinalized{false};
                bool isOverlap{false};
                bool useBeamspot{false};
                bool needLineUpdate{false};
                
                std::array<uint8_t, s_nStations> nMeasurementLayers{};
                std::array<std::vector<CandidateHit>, s_nStations> hitsPerStation{};
                std::vector<HitPayload> phiOnlyHits{};

                bool operator==(const PatternState& other) const = delete;
                void print(std::ostream& ostr, bool detailed) const;
            };
            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& startPatterns,
                                PatternStateVec& endPatterns,
                                const CandidateHit& testHit,
                                const Amg::Vector3D& beamSpot,
                                PatternHitVisualInfoVec* visualInfo = nullptr) const;
            bool passPatternCuts(const PatternState& pat) const;
            static bool isBetter(const PatternState& a, 
                                 const PatternState& b);
            PatternStateVec resolveOverlaps(PatternStateVec& toResolve,
                                            PatternHitVisualInfoVec* visualInfo = nullptr) const;
            void addPhiOnlyHits(const ActsTrk::GeometryContext& gctx,
                                PatternStateVec& patterns) 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);
            static bool areConsecutiveMdt(const CandidateHit& hit1, 
                                          const CandidateHit& hit2);
            void addVisualInfo(const PatternState& candidate, 
                               PatternHitVisualInfo::PatternStatus status,
                               PatternHitVisualInfoVec* visualInfo) const;

            SpacePointPerLayerSorter m_spSorter{};
            Config m_cfg;
 
            struct PatternPrintView {
                const PatternState& pat;
                bool detailed = false;
            };

            static PatternPrintView brief(const PatternState& p);
            static PatternPrintView detailed(const PatternState& p);
            friend std::ostream& operator<<(std::ostream& os, const PatternPrintView& v);
    };
}
 
 
#endif