Propagator/detail/CovarianceEngine.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/Definitions/Algebra.hpp"
0012 #include "Acts/Definitions/TrackParametrization.hpp"
0013 #include "Acts/EventData/TrackParameters.hpp"
0014 #include "Acts/EventData/detail/CorrectedTransformationFreeToBound.hpp"
0015 #include "Acts/Geometry/GeometryContext.hpp"
0016 #include "Acts/Surfaces/Surface.hpp"
0017 #include "Acts/Utilities/Result.hpp"
0018
0019 #include <tuple>
0020
0021 namespace Acts::detail {
0022
0023 /// @brief These functions perform the transport of a covariance matrix using
0024 /// given Jacobians. The required data is provided by the stepper object
0025 /// with some additional data. Since this is a purely algebraic problem the
0026 /// calculations are identical for @c StraightLineStepper and @c EigenStepper.
0027 /// As a consequence the methods can be located in a separate file.
0028
0029 /// Create and return the bound state at the current position
0030 ///
0031 /// @brief It does not check if the transported state is at the surface, this
0032 ///        needs to be guaranteed by the propagator
0033 ///
0034 /// @param [in] geoContext The geometry context
0035 /// @param [in, out] boundCovariance The covariance matrix of the state
0036 /// @param [in, out] fullTransportJacobian Full jacobian since the last reset
0037 /// @param [in, out] freeTransportJacobian Global jacobian since the last reset
0038 /// @param [in, out] freeToPathDerivatives Path length derivatives of the free,
0039 ///        nominal parameters
0040 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0041 ///        parametrisation to free parameters
0042 /// @param [in, out] freeParameters Free, nominal parametrisation
0043 /// @param [in] particleHypothesis Particle hypothesis
0044 /// @param [in] covTransport Decision whether the covariance transport should be
0045 ///        performed
0046 /// @param [in] accumulatedPath Propagated distance
0047 /// @param [in] surface Target surface on which the state is represented
0048 /// @param [in] freeToBoundCorrection Correction for non-linearity effect during
0049 ///        transform from free to bound
0050 ///
0051 /// @return A bound state:
0052 ///   - the parameters at the surface
0053 ///   - the stepwise jacobian towards it (from last bound)
0054 ///   - and the path length (from start - for ordering)
0055 ///
0056 Result<std::tuple<BoundTrackParameters, BoundMatrix, double>> boundState(
0057     const GeometryContext& geoContext, const Surface& surface,
0058     BoundSquareMatrix& boundCovariance, BoundMatrix& fullTransportJacobian,
0059     FreeMatrix& freeTransportJacobian, FreeVector& freeToPathDerivatives,
0060     BoundToFreeMatrix& boundToFreeJacobian,
0061     const std::optional<FreeMatrix>& additionalFreeCovariance,
0062     FreeVector& freeParameters, const ParticleHypothesis& particleHypothesis,
0063     bool covTransport, double accumulatedPath,
0064     const FreeToBoundCorrection& freeToBoundCorrection);
0065
0066 /// Create and return a curvilinear state at the current position
0067 ///
0068 /// @brief This creates a curvilinear state.
0069 ///
0070 /// @param [in, out] boundCovariance The covariance matrix of the state
0071 /// @param [in, out] fullTransportJacobian Full jacobian since the last reset
0072 /// @param [in, out] freeTransportJacobian Global jacobian since the last reset
0073 /// @param [in, out] freeToPathDerivatives Path length derivatives of the free,
0074 ///        nominal parameters
0075 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0076 ///        parametrisation to free parameters
0077 /// @param [in] freeParameters Free, nominal parametrisation
0078 /// @param [in] particleHypothesis Particle hypothesis
0079 /// @param [in] covTransport Decision whether the covariance transport should be
0080 ///        performed
0081 /// @param [in] accumulatedPath Propagated distance
0082 ///
0083 /// @return A curvilinear state:
0084 ///   - the curvilinear parameters at given position
0085 ///   - the stepweise jacobian towards it (from last bound)
0086 ///   - and the path length (from start - for ordering)
0087 std::tuple<BoundTrackParameters, BoundMatrix, double> curvilinearState(
0088     BoundSquareMatrix& boundCovariance, BoundMatrix& fullTransportJacobian,
0089     FreeMatrix& transportJacobian, FreeVector& freeToPathDerivatives,
0090     BoundToFreeMatrix& boundToFreeJacobian,
0091     const std::optional<FreeMatrix>& additionalFreeCovariance,
0092     const FreeVector& freeParameters,
0093     const ParticleHypothesis& particleHypothesis, bool covTransport,
0094     double accumulatedPath);
0095
0096 /// @brief Method for on-demand covariance transport of a bound/curvilinear to
0097 ///        another bound representation.
0098 ///
0099 /// @param [in] geoContext The geometry context
0100 /// @param [in] surface is the surface to which the covariance is forwarded to
0101 /// @param [in, out] boundCovariance The covariance matrix of the state
0102 /// @param [in, out] fullTransportJacobian Full jacobian since the last reset
0103 /// @param [in, out] freeTransportJacobian Global jacobian since the last reset
0104 /// @param [in, out] freeToPathDerivatives Path length derivatives
0105 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0106 ///        parametrisation to free parameters
0107 /// @param [in, out] freeParameters Free, nominal parametrisation
0108 /// @param [in] freeToBoundCorrection Correction for non-linearity effect during
0109 ///        transform from free to bound
0110 ///
0111 /// @note No check is done if the position is actually on the surface
0112 ///
0113 void transportCovarianceToBound(
0114     const GeometryContext& geoContext, const Surface& surface,
0115     BoundSquareMatrix& boundCovariance, BoundMatrix& fullTransportJacobian,
0116     FreeMatrix& freeTransportJacobian, FreeVector& freeToPathDerivatives,
0117     BoundToFreeMatrix& boundToFreeJacobian,
0118     const std::optional<FreeMatrix>& additionalFreeCovariance,
0119     FreeVector& freeParameters,
0120     const FreeToBoundCorrection& freeToBoundCorrection);
0121
0122 /// @brief Method for on-demand covariance transport of a bound/curvilinear
0123 ///        to a new curvilinear representation.
0124 ///
0125 /// @param [in, out] boundCovariance The covariance matrix of the state
0126 /// @param [in, out] fullTransportJacobian Full jacobian since the last reset
0127 /// @param [in, out] freeTransportJacobian Global jacobian since the last reset
0128 /// @param [in, out] freeToPathDerivatives Path length derivatives
0129 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0130 ///        parametrisation to free parameters
0131 /// @param [in] direction Normalised direction vector
0132 ///
0133 void transportCovarianceToCurvilinear(
0134     BoundSquareMatrix& boundCovariance, BoundMatrix& fullTransportJacobian,
0135     FreeMatrix& freeTransportJacobian, FreeVector& freeToPathDerivatives,
0136     BoundToFreeMatrix& boundToFreeJacobian,
0137     const std::optional<FreeMatrix>& additionalFreeCovariance,
0138     const Vector3& direction);
0139
0140 /// Convert bound track parameters to another bound surface.
0141 /// @pre The @p targetSurface must intersect with the surface attached to
0142 ///      @p boundParameters, and the parameters must be on-surface on the
0143 ///      target surface.
0144 /// @param gctx The geometry context.
0145 /// @param boundParameters The bound track parameters to convert.
0146 /// @param targetSurface The target surface.
0147 /// @param bField The magnetic field at the target surface.
0148 /// @return The converted bound track parameters.
0149 Result<BoundTrackParameters> boundToBoundConversion(
0150     const GeometryContext& gctx, const BoundTrackParameters& boundParameters,
0151     const Surface& targetSurface, const Vector3& bField = Vector3::Zero());
0152
0153 }  // namespace Acts::detail