ActsPlugins/Mille/Helpers.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 namespace ActsPlugins::ActsToMille {
0013
0014 /// @brief: Regularise a covariance matrix for decomposition into Mille.
0015 ///         Required especially when running fits with non-timing detectors.
0016 /// @param inputCov: Input covariance matrix, to be regularised
0017 /// @param conditionCutOff: Lowest value (relative to leading EV after clamping)
0018 ///                         to clamp the eigenvalues to.
0019 /// @param removeHugeLeading: If set to a positive value, the leading eigenvalue
0020 ///                           will be regularised to the value of the
0021 ///                           second-leading if the former exceeds the latter by
0022 ///                           more than this factor. Use to suppress poorly
0023 ///                           constrained directions (e.g. time coordinate).
0024 /// @param stabilisationDiag: If set to a positive value, the main diagonal elements
0025 ///                           of the input matrix will be incremented by this
0026 ///                           value to regularise the problem.
0027 /// @param return A new matrix, which has been regularised by clamping
0028 ///               eigenvalues to the iterval [conditionCutOff.first x max_EV,
0029 ///               max_EV], where max_EV is either the leading eigenvalue or, if
0030 ///               removeHugeLeading is positive, either the first or the second
0031 ///               leading EV (second if largest is more than removeHugeLeading
0032 ///               times the second)
0033 Acts::DynamicMatrix regulariseCovariance(const Acts::DynamicMatrix& inputCov,
0034                                          double conditionCutOff = 1e-10,
0035                                          double removeHugeLeading = 100.,
0036                                          double stabilisationDiag = 1.e-10);
0037
0038 /// Calculates the solution X to the matrix equation C = (A + X)^-1,
0039 /// for a poorly conditioned C and known A. Required to decompose the ACTS
0040 /// Kalman covariance matrix into a series of Mille pseudo-measurements.
0041 /// Uses cholesky factorisation of C to solve (1 - CA) = CX
0042 /// to avoid directly inverting C.
0043 /// @param target: The target matrix C to be decomposed - expected to be symmetric
0044 ///                and positive (semi)definite
0045 /// @param existing_sol: The partial existing solution A - expected to be symmetric
0046 /// @return the missing piece X solving the above equation.
0047 Acts::DynamicMatrix getInverseComplement(
0048     const Acts::DynamicMatrix& target, const Acts::DynamicMatrix& existing_sol);
0049
0050 }  // namespace ActsPlugins::ActsToMille