Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2026-11-17 09:41:39

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/Geometry/GeometryContext.hpp"
0012 #include "Acts/Geometry/GeometryHierarchyMap.hpp"
0013 #include "Acts/Geometry/GeometryIdentifier.hpp"
0014 #include "Acts/Utilities/Histogram.hpp"
0015 #include "Acts/Utilities/Logger.hpp"
0016 #include "ActsExamples/EventData/SimHit.hpp"
0017 #include "ActsExamples/EventData/SimParticle.hpp"
0018 #include "ActsExamples/EventData/Track.hpp"
0019 #include "ActsExamples/EventData/TruthMatching.hpp"
0020 #include "ActsExamples/Validation/EffPlotTool.hpp"
0021 #include "ActsExamples/Validation/HistogramFit.hpp"
0022 #include "ActsExamples/Validation/ParametersOnSurface.hpp"
0023 #include "ActsExamples/Validation/ResPlotTool.hpp"
0024 #include "ActsExamples/Validation/TrackSummaryPlotTool.hpp"
0025 
0026 #include <cstddef>
0027 #include <map>
0028 #include <optional>
0029 #include <string>
0030 #include <vector>
0031 
0032 namespace ActsExamples {
0033 
0034 /// Where to take the reconstructed parameters from.
0035 enum class TrackParameterSource {
0036   /// The track parameters at the track reference surface, i.e. the fitter
0037   /// output as delivered.
0038   Track,
0039   /// The parameters of the individual track states, on the surface they sit
0040   /// on.
0041   TrackState,
0042 };
0043 
0044 /// What the reconstructed parameters are compared against.
0045 enum class TrackParameterReference {
0046   /// The truth particle, or the simulated hits behind the measurements.
0047   Truth,
0048   /// The calibrated measurement of the track state itself. Constrains only
0049   /// the local parameters, but needs no truth and therefore also runs on
0050   /// data. `TrackState` source only.
0051   Measurement,
0052 };
0053 
0054 /// Collects performance histograms of the track parameters, without any file
0055 /// I/O.
0056 ///
0057 /// Collects residual/pull histograms, efficiency plots, and track summary
0058 /// information for track fitting performance evaluation. The Gaussian fit
0059 /// backend is supplied by the caller via @c Config::fitFunction.
0060 ///
0061 /// With `parameterSource = Track` the track parameters at the track reference
0062 /// surface are compared to the truth particle. With `TrackState` every
0063 /// selected measurement state is compared on its own surface, which is what
0064 /// makes per-sensor estimates, e.g. from a seed, measurable. The first two
0065 /// bound parameters are local coordinates there, so unnamed parameters are
0066 /// named `loc0`/`loc1` instead of the perigee `d0`/`z0`.
0067 ///
0068 /// `reference` picks what a track state is compared against: the truth behind
0069 /// its measurement, or the measurement itself.
0070 ///
0071 /// @note The caller must ensure exclusive access (e.g. hold a mutex) when
0072 ///       calling fill(). This class applies no locking of its own.
0073 class TrackParameterPerformanceCollector {
0074  public:
0075   struct Config {
0076     /// Empty @c ResPlotTool::Config::paramNames are filled in from
0077     /// @c parameterSource.
0078     ResPlotTool::Config resPlotToolConfig;
0079     EffPlotTool::Config effPlotToolConfig;
0080     TrackSummaryPlotTool::Config trackSummaryPlotToolConfig;
0081 
0082     /// Where to take the reconstructed parameters from.
0083     TrackParameterSource parameterSource = TrackParameterSource::Track;
0084     /// What to compare the reconstructed parameters against. `Measurement` is
0085     /// `TrackState` source only and requires an explicit @c parameterType.
0086     TrackParameterReference reference = TrackParameterReference::Truth;
0087     /// Which track-state parameters to use. If not set, the best available
0088     /// ones (smoothed, filtered, or predicted). `TrackState` source only.
0089     std::optional<TrackParameterType> parameterType;
0090     /// If non-empty, only track states in these geometry regions are used.
0091     /// `TrackState` source only.
0092     std::vector<Acts::GeometryIdentifier> geometrySelection;
0093 
0094     /// The Gaussian fit backend used by @c fitProfiles. If unset,
0095     /// @c fitProfiles logs a warning and returns no profiles.
0096     HistogramFitFunction fitFunction;
0097 
0098     /// Minimum number of entries in a bin for it to be included in the
0099     /// mean/width fit.
0100     int fitMinEntries = 10;
0101     /// The range in sigma for the iterative Gaussian fit
0102     double fitSigmaRange = 3.0;
0103     /// The maximum number of iterations for the iterative Gaussian fit
0104     int fitIterations = 3;
0105     /// Threshold for warning about fit failure fraction in profile
0106     /// extraction.
0107     double warningThresholdFitFailureFraction = 0.55;
0108   };
0109 
0110   TrackParameterPerformanceCollector(
0111       Config cfg, std::unique_ptr<const Acts::Logger> logger);
0112 
0113   /// Fill histograms for one event.
0114   ///
0115   /// @param geoContext the geometry context
0116   /// @param tracks the input tracks
0117   /// @param particles the truth particles
0118   /// @param trackParticleMatching the track to particle matching
0119   /// @param simHits the simulated hits, required for `TrackState`
0120   /// @param measurementSimHitsMap the measurement to simulated hits map,
0121   ///        required for `TrackState`
0122   ///
0123   /// @note The caller must ensure exclusive access (e.g. hold a mutex).
0124   /// @note Only valid with `reference = Truth`.
0125   void fill(const Acts::GeometryContext& geoContext,
0126             const ConstTrackContainer& tracks,
0127             const SimParticleContainer& particles,
0128             const TrackParticleMatching& trackParticleMatching,
0129             const SimHitContainer* simHits = nullptr,
0130             const MeasurementSimHitsMap* measurementSimHitsMap = nullptr);
0131 
0132   /// Fill histograms for one event without any truth information.
0133   ///
0134   /// The efficiency and track summary plots stay empty in this mode.
0135   ///
0136   /// @param tracks the input tracks
0137   ///
0138   /// @note The caller must ensure exclusive access (e.g. hold a mutex).
0139   /// @note Only valid with `reference = Measurement`.
0140   void fill(const ConstTrackContainer& tracks);
0141 
0142   /// Summary count statistics accumulated across all filled events.
0143   struct Stats {
0144     std::size_t nTotalTracks = 0;
0145     std::size_t nTotalMatchedTracks = 0;
0146     std::size_t nTotalFakeTracks = 0;
0147     std::size_t nTotalParticles = 0;
0148     std::size_t nTotalMatchedParticles = 0;
0149     /// Track states skipped for lack of the requested parameters.
0150     std::size_t nMissingStateParameters = 0;
0151     /// Track states skipped for lack of truth hits.
0152     std::size_t nMissingStateTruth = 0;
0153     /// Track states skipped for lack of a calibrated measurement.
0154     std::size_t nMissingStateMeasurement = 0;
0155   };
0156 
0157   /// Return accumulated event counts.
0158   const Stats& stats() const { return m_stats; }
0159 
0160   /// Emit summary statistics via the internal logger.
0161   void logSummary() const;
0162 
0163   /// @name Accessors for the underlying plot tools
0164   /// @{
0165   const ResPlotTool& resPlotTool() const { return m_resPlotTool; }
0166   const EffPlotTool& effPlotTool() const { return m_effPlotTool; }
0167   const TrackSummaryPlotTool& trackSummaryPlotTool() const {
0168     return m_trackSummaryPlotTool;
0169   }
0170   /// @}
0171 
0172   /// Mean/width profiles fitted from every residual and pull histogram.
0173   ///
0174   /// @c profiles1 holds the 2D (vs. eta, vs. pT) outputs; @c profiles2 the
0175   /// 3D (vs. eta-phi, vs. eta-pT) ones.
0176   struct FittedProfiles {
0177     std::vector<Acts::Experimental::Histogram1> profiles1;
0178     std::vector<Acts::Experimental::Histogram2> profiles2;
0179   };
0180 
0181   /// Fit every residual/pull profile histogram with @c Config::fitFunction.
0182   ///
0183   /// Warns if a histogram's fit failure fraction reaches
0184   /// @c Config::warningThresholdFitFailureFraction.
0185   FittedProfiles fitProfiles() const;
0186 
0187  private:
0188   const Acts::Logger& logger() const { return *m_logger; }
0189 
0190   /// The truth inputs needed to compare track states against the truth.
0191   struct TrackStateTruth {
0192     const Acts::GeometryContext& geoContext;
0193     const SimParticle& particle;
0194     const SimHitContainer& simHits;
0195     const MeasurementSimHitsMap& measurementSimHitsMap;
0196   };
0197 
0198   /// Fill the residuals of the selected measurement states of one track on
0199   /// their own surfaces.
0200   ///
0201   /// @param track the track to take the states from
0202   /// @param truth the truth inputs for the `Truth` reference; a null pointer
0203   ///        selects the `Measurement` reference
0204   void fillTrackStates(const ConstTrackProxy& track,
0205                        const TrackStateTruth* truth);
0206 
0207   /// Fit every histogram in @p histMap and append the resulting mean/width
0208   /// profiles to @p out, warning on excessive fit failures.
0209   template <std::size_t Dim>
0210   void addFittedProfiles(
0211       const std::map<std::string, Acts::Experimental::Histogram<Dim>>& histMap,
0212       const std::string& meanPrefix, const std::string& widthPrefix,
0213       std::vector<Acts::Experimental::Histogram<Dim - 1>>& out) const;
0214 
0215   Config m_cfg;
0216   std::unique_ptr<const Acts::Logger> m_logger;
0217 
0218   ResPlotTool m_resPlotTool;
0219   EffPlotTool m_effPlotTool;
0220   TrackSummaryPlotTool m_trackSummaryPlotTool;
0221 
0222   Acts::GeometryHierarchyMap<unsigned int> m_geometrySelection;
0223 
0224   Stats m_stats;
0225 };
0226 
0227 }  // namespace ActsExamples