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