Propagator/detail/JacobianEngine.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/Geometry/GeometryContext.hpp"
0013 #include "Acts/Surfaces/Surface.hpp"
0014
0015 namespace Acts::detail {
0016
0017 /// @brief These functions perform the calculation of the Jacobians for the
0018 /// the covariance transport. This is a purely algebraic problem the
0019 /// calculations are identical for @c StraightLineStepper and @c EigenStepper.
0020 /// As a consequence the methods can be located in a separate file.
0021
0022 /// @brief Evaluate the projection Jacobian from free to curvilinear parameters
0023 ///        without transport jacobian.
0024 ///
0025 /// @param [in] direction Normalised direction vector
0026 ///
0027 /// @return Projection Jacobian
0028 FreeToBoundMatrix freeToCurvilinearJacobian(const Vector3& direction);
0029
0030 /// @brief Evaluate the projection Jacobian from curvilinear to free parameters
0031 ///        without transport jacobian.
0032 ///
0033 /// @param [in] direction Normalised direction vector
0034 ///
0035 /// @return Projection Jacobian
0036 BoundToFreeMatrix curvilinearToFreeJacobian(const Vector3& direction);
0037
0038 /// @brief This function calculates the full transport jacobian from a bound
0039 ///        curvilinear representation to a new bound representation
0040 ///
0041 /// @note Modifications of the jacobian related to the projection onto a surface is
0042 /// considered. Since a variation of the start parameters within a given
0043 /// uncertainty would lead to a variation of the end parameters, these need to
0044 /// be propagated onto the target surface. This an approximated approach to
0045 /// treat the (assumed) small change.
0046 ///
0047 /// @param [in] geoContext The geometry Context
0048 /// @param [in] surface Target surface
0049 /// @param [in] freeParameters Free, nominal parametrisation
0050 /// @param [in] boundToFreeJacobian Jacobian from bound to free at start
0051 /// @param [in] freeTransportJacobian Transport jacobian free to free
0052 /// @param [in] freeToPathDerivatives Path length derivatives for free parameters
0053 /// @param [out] fullTransportJacobian A 6x6 transport jacobian from bound to bound
0054 ///
0055 /// @note jac(locA->locB) = jac(gloB->locB)*(1+
0056 ///       pathCorrectionFactor(gloB))*jacTransport(gloA->gloB) *jac(locA->gloA)
0057 void boundToBoundTransportJacobian(const GeometryContext& geoContext,
0058                                    const Surface& surface,
0059                                    const FreeVector& freeParameters,
0060                                    const BoundToFreeMatrix& boundToFreeJacobian,
0061                                    const FreeMatrix& freeTransportJacobian,
0062                                    FreeToBoundMatrix& freeToBoundJacobian,
0063                                    const FreeVector& freeToPathDerivatives,
0064                                    BoundMatrix& fullTransportJacobian);
0065
0066 /// @brief This function calculates the full transport jacobian from a bound
0067 ///        curvilinear representation to a new bound representation
0068 ///
0069 /// @note Modifications of the jacobian related to the projection onto a surface is
0070 /// considered. Since a variation of the start parameters within a given
0071 /// uncertainty would lead to a variation of the end parameters, these need to
0072 /// be propagated onto the target surface. This an approximated approach to
0073 /// treat the (assumed) small change.
0074 ///
0075 /// @param [in] geoContext The geometry Context
0076 /// @param [in] freeParameters Free, nominal parametrisation
0077 /// @param [in] boundToFreeJacobian Jacobian from bound to free at start
0078 /// @param [in] freeTransportJacobian Transport jacobian free to free
0079 /// @param [in] freeToPathDerivatives Path length derivatives for free parameters
0080 /// @param [in] surface Target surface
0081 ///
0082 /// @note jac(locA->locB) = jac(gloB->locB)*(1+
0083 /// pathCorrectionFactor(gloB))*jacTransport(gloA->gloB) *jac(locA->gloA)
0084 ///
0085 /// @return a 6x6 transport jacobian from bound to bound
0086 BoundMatrix boundToBoundTransportJacobian(
0087     const GeometryContext& geoContext, const FreeVector& freeParameters,
0088     const BoundToFreeMatrix& boundToFreeJacobian,
0089     const FreeMatrix& freeTransportJacobian,
0090     const FreeVector& freeToPathDerivatives, const Surface& surface);
0091
0092 /// @brief This function calculates the full jacobian from a given
0093 /// bound/curvilinear parameterisation from a surface to new curvilinear
0094 /// parameterisation.
0095 ///
0096 /// @note Modifications of the jacobian related to the
0097 /// projection onto a curvilinear surface is considered. Since a variation of
0098 /// the start parameters within a given uncertainty would lead to a variation of
0099 /// the end parameters, these need to be propagated onto the target surface.
0100 /// This is an approximated approach to treat the (assumed) small change.
0101 ///
0102 /// @param [in] direction Normalised direction vector
0103 /// @param [in] boundToFreeJacobian Jacobian from bound to free at start
0104 /// @param [in] freeTransportJacobian Transport jacobian free to free
0105 /// @param [in] freeToPathDerivatives Path length derivatives for free parameters
0106 /// @param [out] fullTransportJacobian A 6x6 transport jacobian from curilinear to bound
0107 ///
0108 /// @note The parameter @p surface is only required if projected to bound
0109 /// parameters. In the case of curvilinear parameters the geometry and the
0110 /// position is known and the calculation can be simplified
0111 void boundToCurvilinearTransportJacobian(
0112     const Vector3& direction, const BoundToFreeMatrix& boundToFreeJacobian,
0113     const FreeMatrix& freeTransportJacobian,
0114     FreeToBoundMatrix& freeToBoundJacobian,
0115     const FreeVector& freeToPathDerivatives,
0116     BoundMatrix& fullTransportJacobian);
0117
0118 /// @brief This function calculates the full jacobian from a given
0119 /// bound/curvilinear parameterisation from a new free parameterisation.
0120 ///
0121 /// @param [in] boundToFreeJacobian Jacobian from bound to free at start
0122 /// @param [in] freeTransportJacobian Transport jacobian free to free
0123 ///
0124 /// @return a 8x6 transport jacobian from bound to free
0125 BoundToFreeMatrix boundToFreeTransportJacobian(
0126     const BoundToFreeMatrix& boundToFreeJacobian,
0127     const FreeMatrix& freeTransportJacobian);
0128
0129 /// @brief This function calculates the full jacobian from a given
0130 /// free parametrisation to a new curvilinear bound parametrisation.
0131 ///
0132 /// @note Modifications of the jacobian related to the
0133 /// projection onto the target surface is considered. Since a variation of
0134 /// the start parameters within a given uncertainty would lead to a variation of
0135 /// the end parameters, these need to be propagated onto the target surface.
0136 /// This is an approximated approach to treat the (assumed) small change.
0137 ///
0138 /// @param [in] geoContext The geometry Context
0139 /// @param [in] surface The target surface
0140 /// @param [in] freeParameters Free, nominal parametrisation
0141 /// @param [in] freeTransportJacobian Transport jacobian free to free
0142 /// @param [in] freeToPathDerivatives Path length derivatives for free parameters
0143 /// @param [out] fullTransportJacobian The 6x8 transport jacobian from bound to free
0144 ///
0145 void freeToBoundTransportJacobian(const GeometryContext& geoContext,
0146                                   const Surface& surface,
0147                                   const FreeVector& freeParameters,
0148                                   const FreeMatrix& freeTransportJacobian,
0149                                   const FreeVector& freeToPathDerivatives,
0150                                   FreeToBoundMatrix& fullTransportJacobian);
0151
0152 /// @brief This function calculates the full transport jacobian from a free
0153 /// parameterisation to a bound one. Since a variation of the start
0154 /// parameters within a given uncertainty would lead to a variation of the end
0155 /// parameters, these need to be propagated onto the target surface. This an
0156 /// approximated approach to treat the (assumed) small change.
0157 ///
0158 /// @param [in] direction Normalised direction vector
0159 /// @param [in] freeTransportJacobian Transport jacobian free to free
0160 /// @param [in] freeToPathDerivatives Path length derivatives for free
0161 ///
0162 /// @return a 6x8 transport jacobian from curvilinear to free
0163 FreeToBoundMatrix freeToCurvilinearTransportJacobian(
0164     const Vector3& direction, const FreeMatrix& freeTransportJacobian,
0165     const FreeVector& freeToPathDerivatives);
0166
0167 /// @brief This function reinitialises the state members required for the
0168 ///        covariance transport for usual surfaces
0169 ///
0170 /// Reinitialize jacobian components:
0171 /// ->The transportJacobian is reinitialized to Identity
0172 /// ->The derivatives is reinitialized to Zero
0173 /// ->The boundToFreeJacobian is initialized to that at the current surface
0174 ///
0175 /// @param [in] geoContext The geometry context
0176 /// @param [in] surface The reference surface of the local parametrisation
0177 /// @param [in, out] freeTransportJacobian The transport jacobian from start
0178 ///        free to final free parameters
0179 /// @param [in, out] freeToPathDerivatives Path length derivatives of the free,
0180 ///        nominal parameters
0181 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0182 ///        parametrisation to free parameters
0183 /// @param [in] freeParameters Free, nominal parametrisation
0184 Result<void> reinitializeJacobians(const GeometryContext& geoContext,
0185                                    const Surface& surface,
0186                                    FreeMatrix& freeTransportJacobian,
0187                                    FreeVector& freeToPathDerivatives,
0188                                    BoundToFreeMatrix& boundToFreeJacobian,
0189                                    const FreeVector& freeParameters);
0190
0191 /// @brief This function reinitialises the state members required for the
0192 ///        covariance transport for curvilinear surfaces
0193 ///
0194 /// Reinitialize jacobian components:
0195 /// ->The free transportJacobian is reinitialized to Identity
0196 /// ->The path derivatives is reinitialized to Zero
0197 /// ->The boundToFreeJacobian is reinitialized to that at the current
0198 /// curvilinear surface
0199 ///
0200 /// @param [in, out] freeTransportJacobian The transport jacobian from start
0201 ///        free to final free parameters
0202 /// @param [in, out] derivatives Path length derivatives of the free, nominal
0203 ///        parameters
0204 /// @param [in, out] boundToFreeJacobian Projection jacobian of the last bound
0205 ///        parametrisation to free parameters
0206 /// @param [in] direction Normalised direction vector
0207 void reinitializeJacobians(FreeMatrix& freeTransportJacobian,
0208                            FreeVector& freeToPathDerivatives,
0209                            BoundToFreeMatrix& boundToFreeJacobian,
0210                            const Vector3& direction);
0211
0212 }  // namespace Acts::detail