Acts/Vertexing/HelicalTrackLinearizer.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2019-2023 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 http://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Definitions/Algebra.hpp"
0012 #include "Acts/EventData/TrackParameters.hpp"
0013 #include "Acts/Geometry/GeometryContext.hpp"
0014 #include "Acts/MagneticField/MagneticFieldContext.hpp"
0015 #include "Acts/MagneticField/MagneticFieldProvider.hpp"
0016 #include "Acts/MagneticField/NullBField.hpp"
0017 #include "Acts/Propagator/EigenStepper.hpp"
0018 #include "Acts/Propagator/Propagator.hpp"
0019 #include "Acts/Utilities/Delegate.hpp"
0020 #include "Acts/Utilities/Result.hpp"
0021 #include "Acts/Vertexing/LinearizedTrack.hpp"
0022
0023 #include <memory>
0024
0025 namespace Acts {
0026
0027 /// @class HelicalTrackLinearizer
0028 /// Linearizes the track parameters at the PCA to a user-provided
0029 /// point (linPoint). The track parameters are written as a function
0030 /// of the global PCA position and the momentum of the particle at
0031 /// the PCA. The linearization then reads (see Eq. 5.7 in Ref. (1)):
0032 ///
0033 /// q = A (r - r_0) + B (p - p_0) + c,
0034 ///
0035 /// where q are the Perigee parameters wrt linPoint, {r_0} r is the {initial}
0036 /// 4D PCA position, {p_0} p is the {initial} momentum (phi, theta, q/p) at the
0037 /// PCA, and c is the constant term of the expansion. A and B are matrices of
0038 /// derivatives, denoted hereafter as "positionJacobian" and
0039 /// "momentumJacobian" respectively.
0040 ///
0041 /// This class computes A and B using the analytic formulae of Ref. (1).
0042 ///
0043 /// Ref. (1) - CERN-THESIS-2010-027, Giacinto Piacquadio (Freiburg U.)
0044 class HelicalTrackLinearizer {
0045  public:
0046   /// @brief Configuration struct
0047   struct Config {
0048     // The magnetic field
0049     std::shared_ptr<const MagneticFieldProvider> bField =
0050         std::make_shared<NullBField>();
0051
0052     std::shared_ptr<const BasePropagator> propagator;
0053
0054     /// Tolerance determining how close we need to get to the Perigee surface to
0055     /// reach it during propagation
0056     ActsScalar targetTolerance = 1e-12;
0057   };
0058
0059   /// @brief Constructor
0060   ///
0061   /// @param config Configuration object
0062   /// @param _logger a logger instance
0063   HelicalTrackLinearizer(const Config& config,
0064                          std::unique_ptr<const Logger> _logger =
0065                              getDefaultLogger("HelTrkLinProp", Logging::INFO))
0066       : m_cfg(config), m_logger{std::move(_logger)} {
0067     if (!m_cfg.propagator) {
0068       throw std::invalid_argument("HelicalTrackLinearizer: propagator is null");
0069     }
0070   }
0071
0072   /// @brief Function that linearizes BoundTrackParameters at
0073   /// the PCA to a given Perigee surface
0074   ///
0075   /// @param params Parameters to linearize
0076   /// @param linPointTime Time associated to the linearization point
0077   /// @note Transverse plane of the Perigee corresponding to @p linPoint is
0078   /// parallel to the global x-y plane
0079   /// @param perigeeSurface Perigee surface belonging to @p linPoint
0080   /// @param gctx Geometry context
0081   /// @param mctx Magnetic field context
0082   /// @param fieldCache Magnetic field cache
0083   ///
0084   /// @return Linearized track
0085   Result<LinearizedTrack> linearizeTrack(
0086       const BoundTrackParameters& params, double linPointTime,
0087       const Surface& perigeeSurface, const Acts::GeometryContext& gctx,
0088       const Acts::MagneticFieldContext& mctx,
0089       MagneticFieldProvider::Cache& fieldCache) const;
0090
0091  private:
0092   /// Configuration object
0093   const Config m_cfg;
0094
0095   std::unique_ptr<const Logger> m_logger;
0096
0097   const Logger& logger() const { return *m_logger; }
0098 };
0099
0100 }  // namespace Acts