TrackFindingBaseAlg.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
*/
 
#ifndef ACTSTRACKRECONSTRUCTION_TRACKFINDINGBASEALG_H
#define ACTSTRACKRECONSTRUCTION_TRACKFINDINGBASEALG_H
 
// Base Class
#include "AthenaBaseComps/AthReentrantAlgorithm.h"
 
 
// Tools
#include "ActsGeometryInterfaces/ITrackingGeometrySvc.h"
#include "ActsGeometryInterfaces/IGeometryRealmConvTool.h"
#include "ActsToolInterfaces/ITrackParamsEstimationTool.h"
#include "src/TrackStatePrinterTool.h"
 
// ACTS
#include "Acts/EventData/ProxyAccessor.hpp"
 
// ActsTrk
#include "ActsToolInterfaces/IPixelOnTrackCalibratorTool.h"
#include "ActsToolInterfaces/IStripOnTrackCalibratorTool.h"
#include "ActsToolInterfaces/IHGTDOnTrackCalibratorTool.h"
#include "IMeasurementSelector.h"
 
// Athena
#include "AthenaMonitoringKernel/GenericMonitoringTool.h"
 
// Handle Keys
#include "src/detail/Definitions.h"
#include "ActsEvent/TrackContainerHandlesHelper.h"
#include "ActsEvent/TrackContainer.h"
#include "ActsEvent/ContextUtility.h"
 
namespace ActsTrk {
  namespace detail {
    class TrackFindingMeasurements;
    class SharedHitCounter;
  }
 
  class TrackFindingBaseAlg : public AthReentrantAlgorithm {
  public:
    TrackFindingBaseAlg(const std::string &name, ISvcLocator *pSvcLocator);
    ~TrackFindingBaseAlg();
 
    virtual StatusCode initialize() override;
    virtual StatusCode finalize() override;
    virtual StatusCode execute(const EventContext &ctx) const override;
 
  protected:
    using TrackFinderOptions = Acts::CombinatorialKalmanFilterOptions<detail::RecoTrackContainer>;
 
    struct MeasurementSelectorConfig {
       // (measurement, outlier) chi2 cuts for each eta bin and measurement dimension (index 0 not used)
       std::vector<std::array<std::pair<float, float>, 4>> m_chi2CutOffOutlier;
       std::vector<float>                   m_etaBins;
    } m_measurementSelectorConfig;
 
    struct DetectorContextHolder {
      Acts::GeometryContext geometry;
      Acts::MagneticFieldContext magField;
      Acts::CalibrationContext calib;
    };
 
    struct TrackFindingDefaultOptions {
      TrackFinderOptions options;
      TrackFinderOptions secondOptions;
      std::unique_ptr<ActsTrk::IMeasurementSelector> measurementSelector;
    };
 
    // Access Acts::CombinatorialKalmanFilter etc using "pointer to implementation"
    // so we don't have to instantiate the heavily templated classes in the header.
    // To maintain const-correctness, only use this via the accessor functions.
    struct CKF_pimpl;
 
    CKF_pimpl &trackFinder();
    const CKF_pimpl &trackFinder() const;
 
    std::unique_ptr<CKF_pimpl> m_trackFinder;
 
 
    // Tool Handles
    ToolHandle<GenericMonitoringTool> m_monTool{this, "MonTool", "", "Monitoring tool"};
    ServiceHandle<ActsTrk::ITrackingGeometrySvc> m_trackingGeometrySvc{this, "TrackingGeometrySvc", "ActsTrackingGeometrySvc"};
    ToolHandle<ActsTrk::TrackStatePrinterTool> m_trackStatePrinter{this, "TrackStatePrinter", "", "optional track state printer"};
    ToolHandle<ActsTrk::IPixelOnTrackCalibratorTool<detail::RecoTrackStateContainer>> m_pixelCalibTool{this, "PixelCalibrator", "", "Opt. pixel measurement calibrator"};
    ToolHandle<ActsTrk::IStripOnTrackCalibratorTool<detail::RecoTrackStateContainer>> m_stripCalibTool{this, "StripCalibrator", "", "Opt. strip measurement calibrator"};
    ToolHandle<ActsTrk::IHGTDOnTrackCalibratorTool<detail::RecoTrackStateContainer>> m_hgtdCalibTool{this, "HGTDCalibrator", "", "Opt. HGTD measurement calibrator"};
 
    SG::WriteHandleKey<ActsTrk::TrackContainer> m_trackContainerKey{this, "ACTSTracksLocation", "", "Output track collection (ActsTrk variant)"};
    ActsTrk::MutableTrackContainerHandlesHelper m_tracksBackendHandlesHelper{this};

    ContextUtility m_ctxProvider{this};
    // Configuration
    Gaudi::Property<unsigned int> m_maxPropagationStep{this, "maxPropagationStep", 1000, "Maximum number of steps for one propagate call"};
    Gaudi::Property<std::vector<double>> m_etaBins{this, "etaBins", {}, "bins in |eta| to specify variable selections"};
    // Acts::MeasurementSelector selection cuts for associating measurements with predicted track parameters on a surface.
    Gaudi::Property<std::vector<double>> m_chi2CutOffSigma{this, "chi2CutOffSigma", {},
       "MeasurementSelector: maximum local chi2 contribution for each eta bin, in sigma of a 1D Gaussian. The p-value of a two-sided cut at this number of sigma gives the chi2 cut for each measurement dimension."};
    Gaudi::Property<std::vector<double>> m_chi2OutlierCutOffSigma{this, "chi2OutlierCutOffSigma", {},
       "MeasurementSelector: maximum local chi2 contribution for outliers for each eta bin, in sigma, see chi2CutOffSigma. If empty, there is no cut."};
    Gaudi::Property<std::vector<size_t>> m_numMeasurementsCutOff{this, "numMeasurementsCutOff", {}, "MeasurementSelector: maximum number of associated measurements on a single surface"};
    Gaudi::Property<double> m_edgeHoleBorderWidth{this,"EdgeHoleBorderWidth", 0. ,"Width of the border of surfaces (mm) within which holes are not counted as holes."};
    Gaudi::Property<std::vector<std::size_t>> m_ptMinMeasurements{this, "ptMinMeasurements", {}, "if specified for the given seed collection, applies ptMin cut in branch stopper once ptMinMinMeasurements have been encountered"};
    Gaudi::Property<std::vector<std::size_t>> m_absEtaMaxMeasurements{this, "absEtaMaxMeasurements", {}, "if specified for the given seed collection, applies absEtaMax cut in branch stopper once absEtaMaxMeasurements have been encountered"};
    Gaudi::Property<bool> m_doBranchStopper{this, "doBranchStopper", true, "use branch stopper"};
    // The second pass extends a track the first pass already found, so its
    // stopper truncates the extension instead of dropping the track.
    Gaudi::Property<bool> m_doSecondPassBranchStopper{this, "doSecondPassBranchStopper", false, "run the branch stopper in the second pass, keeping instead of dropping"};
    Gaudi::Property<bool> m_doTwoWay{this, "doTwoWay", true, "run CKF twice, first with forward propagation with smoothing, then with backward propagation"};
    Gaudi::Property<bool> m_recordMaterialStates{this, "recordMaterialStates", false, "record track states on surfaces which have material but no measurement; keeping them off is faster, but they have to be on for the multi-component stepper and for anything downstream which needs the full track state sequence"};
    Gaudi::Property<bool> m_inflateCovarianceTwoWay{this, "inflateCovarianceTwoWay", false, "inflate covariance matrix at the beginning of two-way track finding"};
    Gaudi::Property<double> m_twoWayinflateCovarianceFactor{this, "twoWayinflateCovarianceFactor", 1.0, "factor to multiply the initial covariance matrix at the beginning of two-way track finding"};
    Gaudi::Property<double> m_branchStopperPtMinFactor{this, "branchStopperPtMinFactor", 1.0, "factor to multiply ptMin cut when used in the branch stopper"};
    Gaudi::Property<double> m_seedRefitPtMinFactor{this, "seedRefitPtMinFactor", 1.0, "factor to multiply ptMin cut when used in the seed refit"};
    Gaudi::Property<double> m_branchStopperAbsEtaMaxExtra{this, "branchStopperAbsEtaMaxExtra", 0.0, "increase absEtaMax cut when used in the branch stopper"};
    Gaudi::Property<double> m_branchStopperMeasCutReduce{this, "branchStopperMeasCutReduce", 2, "how much to reduce the minMeas requirement for the branch stopper"};
    Gaudi::Property<double> m_branchStopperAbsEtaMeasCut{this, "branchStopperAbsEtaMeasCut", 1.2, "the minimum |eta| to apply the reduction to the minMeas requirement for the branch stopper"};
 
    // Acts::TrackSelector cuts
    // Use max double, because mergeConfdb2.py doesn't like std::numeric_limits<double>::infinity() (produces bad Python "inf.0")
    Gaudi::Property<std::vector<double>> m_phiMin{this, "phiMin", {}, "TrackSelector: phiMin"};
    Gaudi::Property<std::vector<double>> m_phiMax{this, "phiMax", {}, "TrackSelector: phiMax"};
    Gaudi::Property<std::vector<double>> m_etaMin{this, "etaMin", {}, "TrackSelector: etaMin"};
    Gaudi::Property<std::vector<double>> m_etaMax{this, "etaMax", {}, "TrackSelector: etaMax"};
    Gaudi::Property<double> m_absEtaMin{this, "absEtaMin", 0.0, "TrackSelector: absEtaMin"};
    Gaudi::Property<double> m_absEtaMax{this, "absEtaMax", std::numeric_limits<double>::max(), "TrackSelector: absEtaMax"};
    Gaudi::Property<std::vector<double>> m_ptMin{this, "ptMin", {}, "TrackSelector: ptMin"};
    Gaudi::Property<std::vector<double>> m_ptMax{this, "ptMax", {}, "TrackSelector: ptMax"};
    Gaudi::Property<std::vector<double>> m_d0Min{this, "d0Min", {}, "TrackSelector: d0Min"};
    Gaudi::Property<std::vector<double>> m_d0Max{this, "d0Max", {}, "TrackSelector: d0Max"};
    Gaudi::Property<std::vector<double>> m_z0Min{this, "z0Min", {}, "TrackSelector: z0Min"};
    Gaudi::Property<std::vector<double>> m_z0Max{this, "z0Max", {}, "TrackSelector: z0Max"};
 
    Gaudi::Property<std::vector<std::size_t>> m_minMeasurements{this, "minMeasurements", {}, "TrackSelector: minMeasurements"};
    Gaudi::Property<std::vector<std::size_t>> m_maxHoles{this, "maxHoles", {}, "TrackSelector: maxHoles"};
    Gaudi::Property<std::vector<std::size_t>> m_maxOutliers{this, "maxOutliers", {}, "TrackSelector: maxOutliers"};
    Gaudi::Property<std::vector<std::size_t>> m_maxHolesAndOutliers{this, "maxHolesAndOutliers", {}, "TrackSelector: maximum number of holes and outliers together"};
    Gaudi::Property<std::vector<std::size_t>> m_maxSharedHits{this, "maxSharedHits", {}, "TrackSelector: maxSharedHits"};
    Gaudi::Property<std::vector<double>> m_maxChi2{this, "maxChi2", {}, "TrackSelector: maxChi2"};
 
    Gaudi::Property<bool> m_addCounts{this, "addCounts", true, "keep separate pixel, strip and hgtd counts and apply the following cuts"};
    Gaudi::Property<bool> m_checkCounts{this, "checkCounts", false, "check consistency among track state counts"};
    Gaudi::Property<std::vector<std::size_t>> m_minPixelHits{this, "minPixelHits", {}, "minimum number of pixel hits"};
    Gaudi::Property<std::vector<std::size_t>> m_minStripHits{this, "minStripHits", {}, "minimum number of strip hits"};
    Gaudi::Property<std::vector<std::size_t>> m_minHgtdHits{this, "minHgtdHits", {}, "minimum number of hgtd hits"};
    Gaudi::Property<std::vector<std::size_t>> m_maxPixelHoles{this, "maxPixelHoles", {}, "maximum number of pixel holes"};
    Gaudi::Property<std::vector<std::size_t>> m_maxStripHoles{this, "maxStripHoles", {}, "maximum number of strip holes"};
    Gaudi::Property<std::vector<std::size_t>> m_maxHgtdHoles{this, "maxHgtdHoles", {}, "maximum number of hgtd holes"};
    Gaudi::Property<std::vector<std::size_t>> m_maxPixelOutliers{this, "maxPixelOutliers", {}, "maximum number of pixel outliers"};
    Gaudi::Property<std::vector<std::size_t>> m_maxStripOutliers{this, "maxStripOutliers", {}, "maximum number of strip outliers"};
    Gaudi::Property<std::vector<std::size_t>> m_maxHgtdOutliers{this, "maxHgtdOutliers", {}, "maximum number of hgtd outliers"};

    Gaudi::Property<std::uint32_t> m_envelopeConstraint{this, "EnvelopeConstaint",
                                                      Acts::toUnderlying(ActsTrk::SystemEnvelope::ITkExit)};
 
    Gaudi::Property<std::vector<std::uint32_t>> m_endOfWorldVolumeIds {this, "EndOfTheWorldVolumeIds", {}, ""};
 
    // configuration of statistics tables
    Gaudi::Property<std::vector<float>> m_statEtaBins{this, "StatisticEtaBins", {-4, -2.6, -2, 0, 2., 2.6, 4}, "Gather statistics separately for these bins."};
    Gaudi::Property<std::vector<std::string>> m_seedLabels{this, "SeedLabels", {}, "One label per seed key used in outputs"};
    Gaudi::Property<bool> m_dumpAllStatEtaBins{this, "DumpEtaBinsForAll", false, "Dump eta bins of all statistics counter."};
 
    enum EStat : std::size_t
    {
      kNTotalSeeds,
      kNoTrackParam,
      kNUsedSeeds,
      kNoTrack,
      kNDuplicateSeeds,
      kNNoEstimatedParams,
      kNOutputTracks,
      kNSeedRefitFailure,
      kNRejectedRefinedSeeds,
      kNSelectedTracks,
      kNStoppedTracksMaxHoles,
      kMultipleBranches,
      kNoSecond,
      kNStoppedTracksMinPt,
      kNStoppedTracksMaxEta,
      kNTotalSharedHits,
      kNForcedSeedMeasurements,
      kNResolvedTracks,
      kNStat
    };
 
    using EventStats = std::vector<std::array<unsigned int, kNStat>>;
 
    // initialize measurement selector to be called during initialize
    StatusCode initializeMeasurementSelector();

    [[nodiscard]] std::unique_ptr<ActsTrk::IMeasurementSelector> setMeasurementSelector(
        const EventContext &ctx,
        const detail::TrackFindingMeasurements &measurements,
        TrackFinderOptions &options) const;

    TrackFindingDefaultOptions getDefaultOptions(const EventContext &ctx,
                                                 const DetectorContextHolder &detContext,
                                                 const detail::TrackFindingMeasurements &measurements,
                                                 const Acts::PerigeeSurface* pSurface) const;

    template <class HandleArrayKeyType, class ContainerType>
    StatusCode getContainersFromKeys(
        const EventContext &ctx,
        HandleArrayKeyType &handleKeyArray,
        std::vector<const ContainerType *> &outputContainers,
        std::size_t &sum) const;

    const Acts::TrackSelector::Config &getCuts(double eta) const;
 
    using TrkProxy = detail::RecoTrackContainer::TrackProxy;

    std::vector<typename detail::RecoTrackContainer::TrackProxy>
    doTwoWayTrackFinding(const detail::RecoTrackStateContainerProxy& firstMeasurement,
                         const TrkProxy &trackProxy,
                         detail::RecoTrackContainer &tracksContainerTemp,
                         const TrackFinderOptions &options) const;
 
    static xAOD::UncalibMeasType measurementType (const detail::RecoTrackContainer::TrackStateProxy &trackState);
 
    using BranchStopperResult = Acts::CombinatorialKalmanFilterBranchStopperResult;

    BranchStopperResult stopBranch(
        const detail::RecoTrackContainer::TrackProxy &track,
        const detail::RecoTrackContainer::TrackStateProxy &trackState,
        const Acts::TrackSelector::EtaBinnedConfig &trackSelectorCfg,
        const Acts::GeometryContext &tgContext,
        const detail::MeasurementIndex &measurementIndex,
        const std::size_t typeIndex,
        EventStats::value_type &event_stat_category_i) const;
 
    struct BranchState {
      static constexpr Acts::ProxyAccessor<unsigned int> nPixelHits{"nPixelHits"};
      static constexpr Acts::ProxyAccessor<unsigned int> nStripHits{"nStripHits"};
      static constexpr Acts::ProxyAccessor<unsigned int> nHgtdHits{"nHgtdHits"};
      static constexpr Acts::ProxyAccessor<unsigned int> nPixelHoles{"nPixelHoles"};
      static constexpr Acts::ProxyAccessor<unsigned int> nStripHoles{"nStripHoles"};
      static constexpr Acts::ProxyAccessor<unsigned int> nHgtdHoles{"nHgtdHoles"};
      static constexpr Acts::ProxyAccessor<unsigned int> nPixelOutliers{"nPixelOutliers"};
      static constexpr Acts::ProxyAccessor<unsigned int> nStripOutliers{"nStripOutliers"};
      static constexpr Acts::ProxyAccessor<unsigned int> nHgtdOutliers{"nHgtdOutliers"};
    };
    static constexpr BranchState s_branchState{};
 
    static void addCountsAndProperties(detail::RecoTrackContainer &tracksContainer, bool add_counts);
    static void initCounts(const detail::RecoTrackContainer::TrackProxy &track);
    static void updateCounts(const detail::RecoTrackContainer::TrackProxy &track,
                             Acts::ConstTrackStateTypeMap typeFlags,
                             xAOD::UncalibMeasType detType);
    void checkCounts(const detail::RecoTrackContainer::TrackProxy &track) const;
    std::array<bool, 3> selectCounts(const detail::RecoTrackContainer::TrackProxy &track, double eta) const;
 
    bool selectCountsFinal(const detail::RecoTrackContainer::TrackProxy &track) const;

    const Acts::Logger &logger() const
    {
      return *m_logger;
    }

    std::unique_ptr<const Acts::Logger> m_logger;
 
    // statistics
    void initStatTables();
    void copyStats(const EventStats &event_stat) const;
    void printStatTables() const;
 
    std::size_t nSeedCollections() const {
      return m_seedLabels.size();
    }
    std::size_t seedCollectionStride() const {
      return m_statEtaBins.size() + 1;
    }
    std::size_t getStatCategory(std::size_t seed_collection, float eta) const;
    std::size_t computeStatSum(std::size_t seed_collection, EStat counter_i, const EventStats &stat) const;
 
    bool m_useAbsEtaForStat = false;
    bool m_showResolvedStats = false;
    mutable std::mutex m_mutex ATLAS_THREAD_SAFE;
    mutable std::vector<std::array<std::size_t, kNStat>> m_stat ATLAS_THREAD_SAFE{};
  };
}  // namespace ActsTrk
 
#include "src/TrackFindingBaseAlg.icc"
 
#endif