Acts/TrackFitting/GsfOptions.hpp

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/EventData/MultiComponentTrackParameters.hpp"
0012 #include "Acts/EventData/MultiTrajectory.hpp"
0013 #include "Acts/Geometry/GeometryContext.hpp"
0014 #include "Acts/MagneticField/MagneticFieldContext.hpp"
0015 #include "Acts/Propagator/PropagatorOptions.hpp"
0016 #include "Acts/TrackFitting/detail/VoidFitterComponents.hpp"
0017 #include "Acts/Utilities/CalibrationContext.hpp"
0018 #include "Acts/Utilities/Delegate.hpp"
0019 #include "Acts/Utilities/Logger.hpp"
0020
0021 namespace Acts {
0022
0023 /// @addtogroup track_fitting
0024 /// @{
0025
0026 /// @enum ComponentMergeMethod
0027 ///
0028 /// Available reduction methods for the reduction of a Gaussian mixture
0029 enum class ComponentMergeMethod { eMean, eMaxWeight };
0030
0031 /// @struct GsfComponent
0032 ///
0033 /// Encapsulates a component of a Gaussian mixture as used by the GSF
0034 struct GsfComponent {
0035   /// Weight of this component in the Gaussian mixture
0036   double weight = 0;
0037   /// Bound track parameters for this component
0038   BoundVector boundPars = BoundVector::Zero();
0039   /// Covariance matrix for the bound track parameters
0040   BoundMatrix boundCov = BoundMatrix::Identity();
0041 };
0042
0043 namespace GsfConstants {
0044 constexpr std::string_view kFinalMultiComponentStateColumn =
0045     "gsf-final-multi-component-state";
0046 using FinalMultiComponentState =
0047     std::optional<MultiComponentBoundTrackParameters>;
0048 constexpr std::string_view kFwdSumMaterialXOverX0 =
0049     "gsf-fwd-sum-material-x-over-x0";
0050 constexpr std::string_view kFwdMaxMaterialXOverX0 =
0051     "gsf-fwd-max-material-x-over-x0";
0052 }  // namespace GsfConstants
0053
0054 /// The extensions needed for the GSF
0055 template <typename traj_t>
0056 struct GsfExtensions {
0057   /// Type alias for mutable track state proxy
0058   using TrackStateProxy = typename traj_t::TrackStateProxy;
0059   /// Type alias for const track state proxy
0060   using ConstTrackStateProxy = typename traj_t::ConstTrackStateProxy;
0061
0062   /// Type alias for calibrator delegate function
0063   using Calibrator =
0064       Delegate<void(const GeometryContext &, const CalibrationContext &,
0065                     const SourceLink &, TrackStateProxy)>;
0066
0067   /// Type alias for updater delegate function
0068   using Updater = Delegate<Result<void>(const GeometryContext &,
0069                                         TrackStateProxy, const Logger &)>;
0070
0071   /// Type alias for outlier finder delegate function
0072   using OutlierFinder = Delegate<bool(ConstTrackStateProxy)>;
0073
0074   /// Type alias for component reducer delegate function
0075   using ComponentReducer =
0076       Delegate<void(std::vector<GsfComponent> &, std::size_t, const Surface &)>;
0077
0078   /// The Calibrator is a dedicated calibration algorithm that allows
0079   /// to calibrate measurements using track information, this could be
0080   /// e.g. sagging for wires, module deformations, etc.
0081   Calibrator calibrator;
0082
0083   /// The updater incorporates measurement information into the track parameters
0084   Updater updater;
0085
0086   /// Determines whether a measurement is supposed to be considered as an
0087   /// outlier
0088   OutlierFinder outlierFinder;
0089
0090   /// Retrieves the associated surface from a source link
0091   SourceLinkSurfaceAccessor surfaceAccessor;
0092
0093   /// Takes a vector of components and reduces its number
0094   ComponentReducer mixtureReducer;
0095
0096   /// Default constructor which connects the default void components
0097   GsfExtensions() {
0098     calibrator.template connect<&detail::voidFitterCalibrator<traj_t>>();
0099     updater.template connect<&detail::voidFitterUpdater<traj_t>>();
0100     outlierFinder.template connect<&detail::voidOutlierFinder<traj_t>>();
0101     surfaceAccessor.connect<&detail::voidSurfaceAccessor>();
0102     mixtureReducer
0103         .template connect<&detail::voidComponentReducer<GsfComponent>>();
0104   }
0105 };
0106
0107 /// Options for configuring the Gaussian-sum filter fit.
0108 template <typename traj_t>
0109 struct GsfOptions {
0110   /// Geometry context for this fit
0111   std::reference_wrapper<const GeometryContext> geoContext;
0112   /// Magnetic field context for this fit
0113   std::reference_wrapper<const MagneticFieldContext> magFieldContext;
0114   /// Calibration context for this fit
0115   std::reference_wrapper<const CalibrationContext> calibrationContext;
0116
0117   /// Extensions for GSF components
0118   GsfExtensions<traj_t> extensions;
0119
0120   /// Propagator options
0121   PropagatorPlainOptions propagatorPlainOptions;
0122
0123   /// Reference surface for the final track parameters
0124   const Surface *referenceSurface = nullptr;
0125
0126   /// Maximum number of components in the mixture
0127   std::size_t maxComponents = 4;
0128
0129   /// Minimum weight required to keep a component
0130   double weightCutoff = 1.e-4;
0131
0132   /// Abort the fit if an error occurs
0133   bool abortOnError = false;
0134
0135   /// Disable all material handling during the fit
0136   bool disableAllMaterialHandling = false;
0137
0138   /// Scaling factor for the covariance matrix before reverse filtering.
0139   /// Note that the default value is not tuned and might need adjustment for
0140   /// different use cases.
0141   double reverseFilteringCovarianceScaling = 100.0;
0142
0143   /// Whether to use the external-surfaces mechanism of the navigator which
0144   /// switches off the boundary-check for measurement surfaces.
0145   bool useExternalSurfaces = true;
0146
0147   /// Column name for final multi-component state storage
0148   std::string_view finalMultiComponentStateColumn = "";
0149
0150   /// Method for merging components
0151   ComponentMergeMethod componentMergeMethod = ComponentMergeMethod::eMaxWeight;
0152
0153   /// Constructor from contexts
0154   /// @param geoCtxt The geometry context
0155   /// @param magFieldCtxt The magnetic field context
0156   /// @param calibCtxt The calibration context
0157   GsfOptions(const GeometryContext &geoCtxt,
0158              const MagneticFieldContext &magFieldCtxt,
0159              const CalibrationContext &calibCtxt)
0160       : geoContext(geoCtxt),
0161         magFieldContext(magFieldCtxt),
0162         calibrationContext(calibCtxt),
0163         propagatorPlainOptions(geoCtxt, magFieldCtxt) {}
0164 };
0165
0166 /// @}
0167
0168 }  // namespace Acts