Michael Ernst Peter / Eigen

Eigen libary for mbed

src/Eigenvalues/Tridiagonalization.h@1:3b8049da21b8, 2019-09-24 (annotated)

Committer:
jsoh91
Date:
Tue Sep 24 00:18:23 2019 +0000
Revision:
1:3b8049da21b8
Parent:
0:13a5d365ba16 
ignore and revise some of error parts

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ykuroda 0:13a5d365ba16 1 // This file is part of Eigen, a lightweight C++ template library
ykuroda 0:13a5d365ba16 2 // for linear algebra.
ykuroda 0:13a5d365ba16 3 //
ykuroda 0:13a5d365ba16 4 // Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
ykuroda 0:13a5d365ba16 5 // Copyright (C) 2010 Jitse Niesen <jitse@maths.leeds.ac.uk>
ykuroda 0:13a5d365ba16 6 //
ykuroda 0:13a5d365ba16 7 // This Source Code Form is subject to the terms of the Mozilla
ykuroda 0:13a5d365ba16 8 // Public License v. 2.0. If a copy of the MPL was not distributed
ykuroda 0:13a5d365ba16 9 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
ykuroda 0:13a5d365ba16 10
ykuroda 0:13a5d365ba16 11 #ifndef EIGEN_TRIDIAGONALIZATION_H
ykuroda 0:13a5d365ba16 12 #define EIGEN_TRIDIAGONALIZATION_H
ykuroda 0:13a5d365ba16 13
ykuroda 0:13a5d365ba16 14 namespace Eigen {
ykuroda 0:13a5d365ba16 15
ykuroda 0:13a5d365ba16 16 namespace internal {
ykuroda 0:13a5d365ba16 17
ykuroda 0:13a5d365ba16 18 template<typename MatrixType> struct TridiagonalizationMatrixTReturnType;
ykuroda 0:13a5d365ba16 19 template<typename MatrixType>
ykuroda 0:13a5d365ba16 20 struct traits<TridiagonalizationMatrixTReturnType<MatrixType> >
ykuroda 0:13a5d365ba16 21 {
ykuroda 0:13a5d365ba16 22 typedef typename MatrixType::PlainObject ReturnType;
ykuroda 0:13a5d365ba16 23 };
ykuroda 0:13a5d365ba16 24
ykuroda 0:13a5d365ba16 25 template<typename MatrixType, typename CoeffVectorType>
ykuroda 0:13a5d365ba16 26 void tridiagonalization_inplace(MatrixType& matA, CoeffVectorType& hCoeffs);
ykuroda 0:13a5d365ba16 27 }
ykuroda 0:13a5d365ba16 28
ykuroda 0:13a5d365ba16 29 /** \eigenvalues_module \ingroup Eigenvalues_Module
ykuroda 0:13a5d365ba16 30 *
ykuroda 0:13a5d365ba16 31 *
ykuroda 0:13a5d365ba16 32 * \class Tridiagonalization
ykuroda 0:13a5d365ba16 33 *
ykuroda 0:13a5d365ba16 34 * \brief Tridiagonal decomposition of a selfadjoint matrix
ykuroda 0:13a5d365ba16 35 *
ykuroda 0:13a5d365ba16 36 * \tparam _MatrixType the type of the matrix of which we are computing the
ykuroda 0:13a5d365ba16 37 * tridiagonal decomposition; this is expected to be an instantiation of the
ykuroda 0:13a5d365ba16 38 * Matrix class template.
ykuroda 0:13a5d365ba16 39 *
ykuroda 0:13a5d365ba16 40 * This class performs a tridiagonal decomposition of a selfadjoint matrix \f$ A \f$ such that:
ykuroda 0:13a5d365ba16 41 * \f$ A = Q T Q^* \f$ where \f$ Q \f$ is unitary and \f$ T \f$ a real symmetric tridiagonal matrix.
ykuroda 0:13a5d365ba16 42 *
ykuroda 0:13a5d365ba16 43 * A tridiagonal matrix is a matrix which has nonzero elements only on the
ykuroda 0:13a5d365ba16 44 * main diagonal and the first diagonal below and above it. The Hessenberg
ykuroda 0:13a5d365ba16 45 * decomposition of a selfadjoint matrix is in fact a tridiagonal
ykuroda 0:13a5d365ba16 46 * decomposition. This class is used in SelfAdjointEigenSolver to compute the
ykuroda 0:13a5d365ba16 47 * eigenvalues and eigenvectors of a selfadjoint matrix.
ykuroda 0:13a5d365ba16 48 *
ykuroda 0:13a5d365ba16 49 * Call the function compute() to compute the tridiagonal decomposition of a
ykuroda 0:13a5d365ba16 50 * given matrix. Alternatively, you can use the Tridiagonalization(const MatrixType&)
ykuroda 0:13a5d365ba16 51 * constructor which computes the tridiagonal Schur decomposition at
ykuroda 0:13a5d365ba16 52 * construction time. Once the decomposition is computed, you can use the
ykuroda 0:13a5d365ba16 53 * matrixQ() and matrixT() functions to retrieve the matrices Q and T in the
ykuroda 0:13a5d365ba16 54 * decomposition.
ykuroda 0:13a5d365ba16 55 *
ykuroda 0:13a5d365ba16 56 * The documentation of Tridiagonalization(const MatrixType&) contains an
ykuroda 0:13a5d365ba16 57 * example of the typical use of this class.
ykuroda 0:13a5d365ba16 58 *
ykuroda 0:13a5d365ba16 59 * \sa class HessenbergDecomposition, class SelfAdjointEigenSolver
ykuroda 0:13a5d365ba16 60 */
ykuroda 0:13a5d365ba16 61 template<typename _MatrixType> class Tridiagonalization
ykuroda 0:13a5d365ba16 62 {
ykuroda 0:13a5d365ba16 63 public:
ykuroda 0:13a5d365ba16 64
ykuroda 0:13a5d365ba16 65 /** \brief Synonym for the template parameter \p _MatrixType. */
ykuroda 0:13a5d365ba16 66 typedef _MatrixType MatrixType;
ykuroda 0:13a5d365ba16 67
ykuroda 0:13a5d365ba16 68 typedef typename MatrixType::Scalar Scalar;
ykuroda 0:13a5d365ba16 69 typedef typename NumTraits<Scalar>::Real RealScalar;
ykuroda 0:13a5d365ba16 70 typedef typename MatrixType::Index Index;
ykuroda 0:13a5d365ba16 71
ykuroda 0:13a5d365ba16 72 enum {
ykuroda 0:13a5d365ba16 73 Size = MatrixType::RowsAtCompileTime,
ykuroda 0:13a5d365ba16 74 SizeMinusOne = Size == Dynamic ? Dynamic : (Size > 1 ? Size - 1 : 1),
ykuroda 0:13a5d365ba16 75 Options = MatrixType::Options,
ykuroda 0:13a5d365ba16 76 MaxSize = MatrixType::MaxRowsAtCompileTime,
ykuroda 0:13a5d365ba16 77 MaxSizeMinusOne = MaxSize == Dynamic ? Dynamic : (MaxSize > 1 ? MaxSize - 1 : 1)
ykuroda 0:13a5d365ba16 78 };
ykuroda 0:13a5d365ba16 79
ykuroda 0:13a5d365ba16 80 typedef Matrix<Scalar, SizeMinusOne, 1, Options & ~RowMajor, MaxSizeMinusOne, 1> CoeffVectorType;
ykuroda 0:13a5d365ba16 81 typedef typename internal::plain_col_type<MatrixType, RealScalar>::type DiagonalType;
ykuroda 0:13a5d365ba16 82 typedef Matrix<RealScalar, SizeMinusOne, 1, Options & ~RowMajor, MaxSizeMinusOne, 1> SubDiagonalType;
ykuroda 0:13a5d365ba16 83 typedef typename internal::remove_all<typename MatrixType::RealReturnType>::type MatrixTypeRealView;
ykuroda 0:13a5d365ba16 84 typedef internal::TridiagonalizationMatrixTReturnType<MatrixTypeRealView> MatrixTReturnType;
ykuroda 0:13a5d365ba16 85
ykuroda 0:13a5d365ba16 86 typedef typename internal::conditional<NumTraits<Scalar>::IsComplex,
ykuroda 0:13a5d365ba16 87 typename internal::add_const_on_value_type<typename Diagonal<const MatrixType>::RealReturnType>::type,
ykuroda 0:13a5d365ba16 88 const Diagonal<const MatrixType>
ykuroda 0:13a5d365ba16 89 >::type DiagonalReturnType;
ykuroda 0:13a5d365ba16 90
ykuroda 0:13a5d365ba16 91 typedef typename internal::conditional<NumTraits<Scalar>::IsComplex,
ykuroda 0:13a5d365ba16 92 typename internal::add_const_on_value_type<typename Diagonal<
ykuroda 0:13a5d365ba16 93 Block<const MatrixType,SizeMinusOne,SizeMinusOne> >::RealReturnType>::type,
ykuroda 0:13a5d365ba16 94 const Diagonal<
ykuroda 0:13a5d365ba16 95 Block<const MatrixType,SizeMinusOne,SizeMinusOne> >
ykuroda 0:13a5d365ba16 96 >::type SubDiagonalReturnType;
ykuroda 0:13a5d365ba16 97
ykuroda 0:13a5d365ba16 98 /** \brief Return type of matrixQ() */
ykuroda 0:13a5d365ba16 99 typedef HouseholderSequence<MatrixType,typename internal::remove_all<typename CoeffVectorType::ConjugateReturnType>::type> HouseholderSequenceType;
ykuroda 0:13a5d365ba16 100
ykuroda 0:13a5d365ba16 101 /** \brief Default constructor.
ykuroda 0:13a5d365ba16 102 *
ykuroda 0:13a5d365ba16 103 * \param [in] size Positive integer, size of the matrix whose tridiagonal
ykuroda 0:13a5d365ba16 104 * decomposition will be computed.
ykuroda 0:13a5d365ba16 105 *
ykuroda 0:13a5d365ba16 106 * The default constructor is useful in cases in which the user intends to
ykuroda 0:13a5d365ba16 107 * perform decompositions via compute(). The \p size parameter is only
ykuroda 0:13a5d365ba16 108 * used as a hint. It is not an error to give a wrong \p size, but it may
ykuroda 0:13a5d365ba16 109 * impair performance.
ykuroda 0:13a5d365ba16 110 *
ykuroda 0:13a5d365ba16 111 * \sa compute() for an example.
ykuroda 0:13a5d365ba16 112 */
ykuroda 0:13a5d365ba16 113 Tridiagonalization(Index size = Size==Dynamic ? 2 : Size)
ykuroda 0:13a5d365ba16 114 : m_matrix(size,size),
ykuroda 0:13a5d365ba16 115 m_hCoeffs(size > 1 ? size-1 : 1),
ykuroda 0:13a5d365ba16 116 m_isInitialized(false)
ykuroda 0:13a5d365ba16 117 {}
ykuroda 0:13a5d365ba16 118
ykuroda 0:13a5d365ba16 119 /** \brief Constructor; computes tridiagonal decomposition of given matrix.
ykuroda 0:13a5d365ba16 120 *
ykuroda 0:13a5d365ba16 121 * \param[in] matrix Selfadjoint matrix whose tridiagonal decomposition
ykuroda 0:13a5d365ba16 122 * is to be computed.
ykuroda 0:13a5d365ba16 123 *
ykuroda 0:13a5d365ba16 124 * This constructor calls compute() to compute the tridiagonal decomposition.
ykuroda 0:13a5d365ba16 125 *
ykuroda 0:13a5d365ba16 126 * Example: \include Tridiagonalization_Tridiagonalization_MatrixType.cpp
ykuroda 0:13a5d365ba16 127 * Output: \verbinclude Tridiagonalization_Tridiagonalization_MatrixType.out
ykuroda 0:13a5d365ba16 128 */
ykuroda 0:13a5d365ba16 129 Tridiagonalization(const MatrixType& matrix)
ykuroda 0:13a5d365ba16 130 : m_matrix(matrix),
ykuroda 0:13a5d365ba16 131 m_hCoeffs(matrix.cols() > 1 ? matrix.cols()-1 : 1),
ykuroda 0:13a5d365ba16 132 m_isInitialized(false)
ykuroda 0:13a5d365ba16 133 {
ykuroda 0:13a5d365ba16 134 internal::tridiagonalization_inplace(m_matrix, m_hCoeffs);
ykuroda 0:13a5d365ba16 135 m_isInitialized = true;
ykuroda 0:13a5d365ba16 136 }
ykuroda 0:13a5d365ba16 137
ykuroda 0:13a5d365ba16 138 /** \brief Computes tridiagonal decomposition of given matrix.
ykuroda 0:13a5d365ba16 139 *
ykuroda 0:13a5d365ba16 140 * \param[in] matrix Selfadjoint matrix whose tridiagonal decomposition
ykuroda 0:13a5d365ba16 141 * is to be computed.
ykuroda 0:13a5d365ba16 142 * \returns Reference to \c *this
ykuroda 0:13a5d365ba16 143 *
ykuroda 0:13a5d365ba16 144 * The tridiagonal decomposition is computed by bringing the columns of
ykuroda 0:13a5d365ba16 145 * the matrix successively in the required form using Householder
ykuroda 0:13a5d365ba16 146 * reflections. The cost is \f$ 4n^3/3 \f$ flops, where \f$ n \f$ denotes
ykuroda 0:13a5d365ba16 147 * the size of the given matrix.
ykuroda 0:13a5d365ba16 148 *
ykuroda 0:13a5d365ba16 149 * This method reuses of the allocated data in the Tridiagonalization
ykuroda 0:13a5d365ba16 150 * object, if the size of the matrix does not change.
ykuroda 0:13a5d365ba16 151 *
ykuroda 0:13a5d365ba16 152 * Example: \include Tridiagonalization_compute.cpp
ykuroda 0:13a5d365ba16 153 * Output: \verbinclude Tridiagonalization_compute.out
ykuroda 0:13a5d365ba16 154 */
ykuroda 0:13a5d365ba16 155 Tridiagonalization& compute(const MatrixType& matrix)
ykuroda 0:13a5d365ba16 156 {
ykuroda 0:13a5d365ba16 157 m_matrix = matrix;
ykuroda 0:13a5d365ba16 158 m_hCoeffs.resize(matrix.rows()-1, 1);
ykuroda 0:13a5d365ba16 159 internal::tridiagonalization_inplace(m_matrix, m_hCoeffs);
ykuroda 0:13a5d365ba16 160 m_isInitialized = true;
ykuroda 0:13a5d365ba16 161 return *this;
ykuroda 0:13a5d365ba16 162 }
ykuroda 0:13a5d365ba16 163
ykuroda 0:13a5d365ba16 164 /** \brief Returns the Householder coefficients.
ykuroda 0:13a5d365ba16 165 *
ykuroda 0:13a5d365ba16 166 * \returns a const reference to the vector of Householder coefficients
ykuroda 0:13a5d365ba16 167 *
ykuroda 0:13a5d365ba16 168 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 169 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 170 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 171 *
ykuroda 0:13a5d365ba16 172 * The Householder coefficients allow the reconstruction of the matrix
ykuroda 0:13a5d365ba16 173 * \f$ Q \f$ in the tridiagonal decomposition from the packed data.
ykuroda 0:13a5d365ba16 174 *
ykuroda 0:13a5d365ba16 175 * Example: \include Tridiagonalization_householderCoefficients.cpp
ykuroda 0:13a5d365ba16 176 * Output: \verbinclude Tridiagonalization_householderCoefficients.out
ykuroda 0:13a5d365ba16 177 *
ykuroda 0:13a5d365ba16 178 * \sa packedMatrix(), \ref Householder_Module "Householder module"
ykuroda 0:13a5d365ba16 179 */
ykuroda 0:13a5d365ba16 180 inline CoeffVectorType householderCoefficients() const
ykuroda 0:13a5d365ba16 181 {
ykuroda 0:13a5d365ba16 182 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 183 return m_hCoeffs;
ykuroda 0:13a5d365ba16 184 }
ykuroda 0:13a5d365ba16 185
ykuroda 0:13a5d365ba16 186 /** \brief Returns the internal representation of the decomposition
ykuroda 0:13a5d365ba16 187 *
ykuroda 0:13a5d365ba16 188 * \returns a const reference to a matrix with the internal representation
ykuroda 0:13a5d365ba16 189 * of the decomposition.
ykuroda 0:13a5d365ba16 190 *
ykuroda 0:13a5d365ba16 191 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 192 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 193 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 194 *
ykuroda 0:13a5d365ba16 195 * The returned matrix contains the following information:
ykuroda 0:13a5d365ba16 196 * - the strict upper triangular part is equal to the input matrix A.
ykuroda 0:13a5d365ba16 197 * - the diagonal and lower sub-diagonal represent the real tridiagonal
ykuroda 0:13a5d365ba16 198 * symmetric matrix T.
ykuroda 0:13a5d365ba16 199 * - the rest of the lower part contains the Householder vectors that,
ykuroda 0:13a5d365ba16 200 * combined with Householder coefficients returned by
ykuroda 0:13a5d365ba16 201 * householderCoefficients(), allows to reconstruct the matrix Q as
ykuroda 0:13a5d365ba16 202 * \f$ Q = H_{N-1} \ldots H_1 H_0 \f$.
ykuroda 0:13a5d365ba16 203 * Here, the matrices \f$ H_i \f$ are the Householder transformations
ykuroda 0:13a5d365ba16 204 * \f$ H_i = (I - h_i v_i v_i^T) \f$
ykuroda 0:13a5d365ba16 205 * where \f$ h_i \f$ is the \f$ i \f$th Householder coefficient and
ykuroda 0:13a5d365ba16 206 * \f$ v_i \f$ is the Householder vector defined by
ykuroda 0:13a5d365ba16 207 * \f$ v_i = [ 0, \ldots, 0, 1, M(i+2,i), \ldots, M(N-1,i) ]^T \f$
ykuroda 0:13a5d365ba16 208 * with M the matrix returned by this function.
ykuroda 0:13a5d365ba16 209 *
ykuroda 0:13a5d365ba16 210 * See LAPACK for further details on this packed storage.
ykuroda 0:13a5d365ba16 211 *
ykuroda 0:13a5d365ba16 212 * Example: \include Tridiagonalization_packedMatrix.cpp
ykuroda 0:13a5d365ba16 213 * Output: \verbinclude Tridiagonalization_packedMatrix.out
ykuroda 0:13a5d365ba16 214 *
ykuroda 0:13a5d365ba16 215 * \sa householderCoefficients()
ykuroda 0:13a5d365ba16 216 */
ykuroda 0:13a5d365ba16 217 inline const MatrixType& packedMatrix() const
ykuroda 0:13a5d365ba16 218 {
ykuroda 0:13a5d365ba16 219 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 220 return m_matrix;
ykuroda 0:13a5d365ba16 221 }
ykuroda 0:13a5d365ba16 222
ykuroda 0:13a5d365ba16 223 /** \brief Returns the unitary matrix Q in the decomposition
ykuroda 0:13a5d365ba16 224 *
ykuroda 0:13a5d365ba16 225 * \returns object representing the matrix Q
ykuroda 0:13a5d365ba16 226 *
ykuroda 0:13a5d365ba16 227 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 228 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 229 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 230 *
ykuroda 0:13a5d365ba16 231 * This function returns a light-weight object of template class
ykuroda 0:13a5d365ba16 232 * HouseholderSequence. You can either apply it directly to a matrix or
ykuroda 0:13a5d365ba16 233 * you can convert it to a matrix of type #MatrixType.
ykuroda 0:13a5d365ba16 234 *
ykuroda 0:13a5d365ba16 235 * \sa Tridiagonalization(const MatrixType&) for an example,
ykuroda 0:13a5d365ba16 236 * matrixT(), class HouseholderSequence
ykuroda 0:13a5d365ba16 237 */
ykuroda 0:13a5d365ba16 238 HouseholderSequenceType matrixQ() const
ykuroda 0:13a5d365ba16 239 {
ykuroda 0:13a5d365ba16 240 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 241 return HouseholderSequenceType(m_matrix, m_hCoeffs.conjugate())
ykuroda 0:13a5d365ba16 242 .setLength(m_matrix.rows() - 1)
ykuroda 0:13a5d365ba16 243 .setShift(1);
ykuroda 0:13a5d365ba16 244 }
ykuroda 0:13a5d365ba16 245
ykuroda 0:13a5d365ba16 246 /** \brief Returns an expression of the tridiagonal matrix T in the decomposition
ykuroda 0:13a5d365ba16 247 *
ykuroda 0:13a5d365ba16 248 * \returns expression object representing the matrix T
ykuroda 0:13a5d365ba16 249 *
ykuroda 0:13a5d365ba16 250 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 251 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 252 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 253 *
ykuroda 0:13a5d365ba16 254 * Currently, this function can be used to extract the matrix T from internal
ykuroda 0:13a5d365ba16 255 * data and copy it to a dense matrix object. In most cases, it may be
ykuroda 0:13a5d365ba16 256 * sufficient to directly use the packed matrix or the vector expressions
ykuroda 0:13a5d365ba16 257 * returned by diagonal() and subDiagonal() instead of creating a new
ykuroda 0:13a5d365ba16 258 * dense copy matrix with this function.
ykuroda 0:13a5d365ba16 259 *
ykuroda 0:13a5d365ba16 260 * \sa Tridiagonalization(const MatrixType&) for an example,
ykuroda 0:13a5d365ba16 261 * matrixQ(), packedMatrix(), diagonal(), subDiagonal()
ykuroda 0:13a5d365ba16 262 */
ykuroda 0:13a5d365ba16 263 MatrixTReturnType matrixT() const
ykuroda 0:13a5d365ba16 264 {
ykuroda 0:13a5d365ba16 265 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 266 return MatrixTReturnType(m_matrix.real());
ykuroda 0:13a5d365ba16 267 }
ykuroda 0:13a5d365ba16 268
ykuroda 0:13a5d365ba16 269 /** \brief Returns the diagonal of the tridiagonal matrix T in the decomposition.
ykuroda 0:13a5d365ba16 270 *
ykuroda 0:13a5d365ba16 271 * \returns expression representing the diagonal of T
ykuroda 0:13a5d365ba16 272 *
ykuroda 0:13a5d365ba16 273 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 274 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 275 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 276 *
ykuroda 0:13a5d365ba16 277 * Example: \include Tridiagonalization_diagonal.cpp
ykuroda 0:13a5d365ba16 278 * Output: \verbinclude Tridiagonalization_diagonal.out
ykuroda 0:13a5d365ba16 279 *
ykuroda 0:13a5d365ba16 280 * \sa matrixT(), subDiagonal()
ykuroda 0:13a5d365ba16 281 */
ykuroda 0:13a5d365ba16 282 DiagonalReturnType diagonal() const;
ykuroda 0:13a5d365ba16 283
ykuroda 0:13a5d365ba16 284 /** \brief Returns the subdiagonal of the tridiagonal matrix T in the decomposition.
ykuroda 0:13a5d365ba16 285 *
ykuroda 0:13a5d365ba16 286 * \returns expression representing the subdiagonal of T
ykuroda 0:13a5d365ba16 287 *
ykuroda 0:13a5d365ba16 288 * \pre Either the constructor Tridiagonalization(const MatrixType&) or
ykuroda 0:13a5d365ba16 289 * the member function compute(const MatrixType&) has been called before
ykuroda 0:13a5d365ba16 290 * to compute the tridiagonal decomposition of a matrix.
ykuroda 0:13a5d365ba16 291 *
ykuroda 0:13a5d365ba16 292 * \sa diagonal() for an example, matrixT()
ykuroda 0:13a5d365ba16 293 */
ykuroda 0:13a5d365ba16 294 SubDiagonalReturnType subDiagonal() const;
ykuroda 0:13a5d365ba16 295
ykuroda 0:13a5d365ba16 296 protected:
ykuroda 0:13a5d365ba16 297
ykuroda 0:13a5d365ba16 298 MatrixType m_matrix;
ykuroda 0:13a5d365ba16 299 CoeffVectorType m_hCoeffs;
ykuroda 0:13a5d365ba16 300 bool m_isInitialized;
ykuroda 0:13a5d365ba16 301 };
ykuroda 0:13a5d365ba16 302
ykuroda 0:13a5d365ba16 303 template<typename MatrixType>
ykuroda 0:13a5d365ba16 304 typename Tridiagonalization<MatrixType>::DiagonalReturnType
ykuroda 0:13a5d365ba16 305 Tridiagonalization<MatrixType>::diagonal() const
ykuroda 0:13a5d365ba16 306 {
ykuroda 0:13a5d365ba16 307 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 308 return m_matrix.diagonal();
ykuroda 0:13a5d365ba16 309 }
ykuroda 0:13a5d365ba16 310
ykuroda 0:13a5d365ba16 311 template<typename MatrixType>
ykuroda 0:13a5d365ba16 312 typename Tridiagonalization<MatrixType>::SubDiagonalReturnType
ykuroda 0:13a5d365ba16 313 Tridiagonalization<MatrixType>::subDiagonal() const
ykuroda 0:13a5d365ba16 314 {
ykuroda 0:13a5d365ba16 315 eigen_assert(m_isInitialized && "Tridiagonalization is not initialized.");
ykuroda 0:13a5d365ba16 316 Index n = m_matrix.rows();
ykuroda 0:13a5d365ba16 317 return Block<const MatrixType,SizeMinusOne,SizeMinusOne>(m_matrix, 1, 0, n-1,n-1).diagonal();
ykuroda 0:13a5d365ba16 318 }
ykuroda 0:13a5d365ba16 319
ykuroda 0:13a5d365ba16 320 namespace internal {
ykuroda 0:13a5d365ba16 321
ykuroda 0:13a5d365ba16 322 /** \internal
ykuroda 0:13a5d365ba16 323 * Performs a tridiagonal decomposition of the selfadjoint matrix \a matA in-place.
ykuroda 0:13a5d365ba16 324 *
ykuroda 0:13a5d365ba16 325 * \param[in,out] matA On input the selfadjoint matrix. Only the \b lower triangular part is referenced.
ykuroda 0:13a5d365ba16 326 * On output, the strict upper part is left unchanged, and the lower triangular part
ykuroda 0:13a5d365ba16 327 * represents the T and Q matrices in packed format has detailed below.
ykuroda 0:13a5d365ba16 328 * \param[out] hCoeffs returned Householder coefficients (see below)
ykuroda 0:13a5d365ba16 329 *
ykuroda 0:13a5d365ba16 330 * On output, the tridiagonal selfadjoint matrix T is stored in the diagonal
ykuroda 0:13a5d365ba16 331 * and lower sub-diagonal of the matrix \a matA.
ykuroda 0:13a5d365ba16 332 * The unitary matrix Q is represented in a compact way as a product of
ykuroda 0:13a5d365ba16 333 * Householder reflectors \f$ H_i \f$ such that:
ykuroda 0:13a5d365ba16 334 * \f$ Q = H_{N-1} \ldots H_1 H_0 \f$.
ykuroda 0:13a5d365ba16 335 * The Householder reflectors are defined as
ykuroda 0:13a5d365ba16 336 * \f$ H_i = (I - h_i v_i v_i^T) \f$
ykuroda 0:13a5d365ba16 337 * where \f$ h_i = hCoeffs[i]\f$ is the \f$ i \f$th Householder coefficient and
ykuroda 0:13a5d365ba16 338 * \f$ v_i \f$ is the Householder vector defined by
ykuroda 0:13a5d365ba16 339 * \f$ v_i = [ 0, \ldots, 0, 1, matA(i+2,i), \ldots, matA(N-1,i) ]^T \f$.
ykuroda 0:13a5d365ba16 340 *
ykuroda 0:13a5d365ba16 341 * Implemented from Golub's "Matrix Computations", algorithm 8.3.1.
ykuroda 0:13a5d365ba16 342 *
ykuroda 0:13a5d365ba16 343 * \sa Tridiagonalization::packedMatrix()
ykuroda 0:13a5d365ba16 344 */
ykuroda 0:13a5d365ba16 345 template<typename MatrixType, typename CoeffVectorType>
ykuroda 0:13a5d365ba16 346 void tridiagonalization_inplace(MatrixType& matA, CoeffVectorType& hCoeffs)
ykuroda 0:13a5d365ba16 347 {
ykuroda 0:13a5d365ba16 348 using numext::conj;
ykuroda 0:13a5d365ba16 349 typedef typename MatrixType::Index Index;
ykuroda 0:13a5d365ba16 350 typedef typename MatrixType::Scalar Scalar;
ykuroda 0:13a5d365ba16 351 typedef typename MatrixType::RealScalar RealScalar;
ykuroda 0:13a5d365ba16 352 Index n = matA.rows();
ykuroda 0:13a5d365ba16 353 eigen_assert(n==matA.cols());
ykuroda 0:13a5d365ba16 354 eigen_assert(n==hCoeffs.size()+1 || n==1);
ykuroda 0:13a5d365ba16 355
ykuroda 0:13a5d365ba16 356 for (Index i = 0; i<n-1; ++i)
ykuroda 0:13a5d365ba16 357 {
ykuroda 0:13a5d365ba16 358 Index remainingSize = n-i-1;
ykuroda 0:13a5d365ba16 359 RealScalar beta;
ykuroda 0:13a5d365ba16 360 Scalar h;
ykuroda 0:13a5d365ba16 361 matA.col(i).tail(remainingSize).makeHouseholderInPlace(h, beta);
ykuroda 0:13a5d365ba16 362
ykuroda 0:13a5d365ba16 363 // Apply similarity transformation to remaining columns,
ykuroda 0:13a5d365ba16 364 // i.e., A = H A H' where H = I - h v v' and v = matA.col(i).tail(n-i-1)
ykuroda 0:13a5d365ba16 365 matA.col(i).coeffRef(i+1) = 1;
ykuroda 0:13a5d365ba16 366
ykuroda 0:13a5d365ba16 367 hCoeffs.tail(n-i-1).noalias() = (matA.bottomRightCorner(remainingSize,remainingSize).template selfadjointView<Lower>()
ykuroda 0:13a5d365ba16 368 * (conj(h) * matA.col(i).tail(remainingSize)));
ykuroda 0:13a5d365ba16 369
ykuroda 0:13a5d365ba16 370 hCoeffs.tail(n-i-1) += (conj(h)*Scalar(-0.5)*(hCoeffs.tail(remainingSize).dot(matA.col(i).tail(remainingSize)))) * matA.col(i).tail(n-i-1);
ykuroda 0:13a5d365ba16 371
ykuroda 0:13a5d365ba16 372 matA.bottomRightCorner(remainingSize, remainingSize).template selfadjointView<Lower>()
ykuroda 0:13a5d365ba16 373 .rankUpdate(matA.col(i).tail(remainingSize), hCoeffs.tail(remainingSize), -1);
ykuroda 0:13a5d365ba16 374
ykuroda 0:13a5d365ba16 375 matA.col(i).coeffRef(i+1) = beta;
ykuroda 0:13a5d365ba16 376 hCoeffs.coeffRef(i) = h;
ykuroda 0:13a5d365ba16 377 }
ykuroda 0:13a5d365ba16 378 }
ykuroda 0:13a5d365ba16 379
ykuroda 0:13a5d365ba16 380 // forward declaration, implementation at the end of this file
ykuroda 0:13a5d365ba16 381 template<typename MatrixType,
ykuroda 0:13a5d365ba16 382 int Size=MatrixType::ColsAtCompileTime,
ykuroda 0:13a5d365ba16 383 bool IsComplex=NumTraits<typename MatrixType::Scalar>::IsComplex>
ykuroda 0:13a5d365ba16 384 struct tridiagonalization_inplace_selector;
ykuroda 0:13a5d365ba16 385
ykuroda 0:13a5d365ba16 386 /** \brief Performs a full tridiagonalization in place
ykuroda 0:13a5d365ba16 387 *
ykuroda 0:13a5d365ba16 388 * \param[in,out] mat On input, the selfadjoint matrix whose tridiagonal
ykuroda 0:13a5d365ba16 389 * decomposition is to be computed. Only the lower triangular part referenced.
ykuroda 0:13a5d365ba16 390 * The rest is left unchanged. On output, the orthogonal matrix Q
ykuroda 0:13a5d365ba16 391 * in the decomposition if \p extractQ is true.
ykuroda 0:13a5d365ba16 392 * \param[out] diag The diagonal of the tridiagonal matrix T in the
ykuroda 0:13a5d365ba16 393 * decomposition.
ykuroda 0:13a5d365ba16 394 * \param[out] subdiag The subdiagonal of the tridiagonal matrix T in
ykuroda 0:13a5d365ba16 395 * the decomposition.
ykuroda 0:13a5d365ba16 396 * \param[in] extractQ If true, the orthogonal matrix Q in the
ykuroda 0:13a5d365ba16 397 * decomposition is computed and stored in \p mat.
ykuroda 0:13a5d365ba16 398 *
ykuroda 0:13a5d365ba16 399 * Computes the tridiagonal decomposition of the selfadjoint matrix \p mat in place
ykuroda 0:13a5d365ba16 400 * such that \f$ mat = Q T Q^* \f$ where \f$ Q \f$ is unitary and \f$ T \f$ a real
ykuroda 0:13a5d365ba16 401 * symmetric tridiagonal matrix.
ykuroda 0:13a5d365ba16 402 *
ykuroda 0:13a5d365ba16 403 * The tridiagonal matrix T is passed to the output parameters \p diag and \p subdiag. If
ykuroda 0:13a5d365ba16 404 * \p extractQ is true, then the orthogonal matrix Q is passed to \p mat. Otherwise the lower
ykuroda 0:13a5d365ba16 405 * part of the matrix \p mat is destroyed.
ykuroda 0:13a5d365ba16 406 *
ykuroda 0:13a5d365ba16 407 * The vectors \p diag and \p subdiag are not resized. The function
ykuroda 0:13a5d365ba16 408 * assumes that they are already of the correct size. The length of the
ykuroda 0:13a5d365ba16 409 * vector \p diag should equal the number of rows in \p mat, and the
ykuroda 0:13a5d365ba16 410 * length of the vector \p subdiag should be one left.
ykuroda 0:13a5d365ba16 411 *
ykuroda 0:13a5d365ba16 412 * This implementation contains an optimized path for 3-by-3 matrices
ykuroda 0:13a5d365ba16 413 * which is especially useful for plane fitting.
ykuroda 0:13a5d365ba16 414 *
ykuroda 0:13a5d365ba16 415 * \note Currently, it requires two temporary vectors to hold the intermediate
ykuroda 0:13a5d365ba16 416 * Householder coefficients, and to reconstruct the matrix Q from the Householder
ykuroda 0:13a5d365ba16 417 * reflectors.
ykuroda 0:13a5d365ba16 418 *
ykuroda 0:13a5d365ba16 419 * Example (this uses the same matrix as the example in
ykuroda 0:13a5d365ba16 420 * Tridiagonalization::Tridiagonalization(const MatrixType&)):
ykuroda 0:13a5d365ba16 421 * \include Tridiagonalization_decomposeInPlace.cpp
ykuroda 0:13a5d365ba16 422 * Output: \verbinclude Tridiagonalization_decomposeInPlace.out
ykuroda 0:13a5d365ba16 423 *
ykuroda 0:13a5d365ba16 424 * \sa class Tridiagonalization
ykuroda 0:13a5d365ba16 425 */
ykuroda 0:13a5d365ba16 426 template<typename MatrixType, typename DiagonalType, typename SubDiagonalType>
ykuroda 0:13a5d365ba16 427 void tridiagonalization_inplace(MatrixType& mat, DiagonalType& diag, SubDiagonalType& subdiag, bool extractQ)
ykuroda 0:13a5d365ba16 428 {
ykuroda 0:13a5d365ba16 429 eigen_assert(mat.cols()==mat.rows() && diag.size()==mat.rows() && subdiag.size()==mat.rows()-1);
ykuroda 0:13a5d365ba16 430 tridiagonalization_inplace_selector<MatrixType>::run(mat, diag, subdiag, extractQ);
ykuroda 0:13a5d365ba16 431 }
ykuroda 0:13a5d365ba16 432
ykuroda 0:13a5d365ba16 433 /** \internal
ykuroda 0:13a5d365ba16 434 * General full tridiagonalization
ykuroda 0:13a5d365ba16 435 */
ykuroda 0:13a5d365ba16 436 template<typename MatrixType, int Size, bool IsComplex>
ykuroda 0:13a5d365ba16 437 struct tridiagonalization_inplace_selector
ykuroda 0:13a5d365ba16 438 {
ykuroda 0:13a5d365ba16 439 typedef typename Tridiagonalization<MatrixType>::CoeffVectorType CoeffVectorType;
ykuroda 0:13a5d365ba16 440 typedef typename Tridiagonalization<MatrixType>::HouseholderSequenceType HouseholderSequenceType;
ykuroda 0:13a5d365ba16 441 typedef typename MatrixType::Index Index;
ykuroda 0:13a5d365ba16 442 template<typename DiagonalType, typename SubDiagonalType>
ykuroda 0:13a5d365ba16 443 static void run(MatrixType& mat, DiagonalType& diag, SubDiagonalType& subdiag, bool extractQ)
ykuroda 0:13a5d365ba16 444 {
ykuroda 0:13a5d365ba16 445 CoeffVectorType hCoeffs(mat.cols()-1);
ykuroda 0:13a5d365ba16 446 tridiagonalization_inplace(mat,hCoeffs);
ykuroda 0:13a5d365ba16 447 diag = mat.diagonal().real();
ykuroda 0:13a5d365ba16 448 subdiag = mat.template diagonal<-1>().real();
ykuroda 0:13a5d365ba16 449 if(extractQ)
ykuroda 0:13a5d365ba16 450 mat = HouseholderSequenceType(mat, hCoeffs.conjugate())
ykuroda 0:13a5d365ba16 451 .setLength(mat.rows() - 1)
ykuroda 0:13a5d365ba16 452 .setShift(1);
ykuroda 0:13a5d365ba16 453 }
ykuroda 0:13a5d365ba16 454 };
ykuroda 0:13a5d365ba16 455
ykuroda 0:13a5d365ba16 456 /** \internal
ykuroda 0:13a5d365ba16 457 * Specialization for 3x3 real matrices.
ykuroda 0:13a5d365ba16 458 * Especially useful for plane fitting.
ykuroda 0:13a5d365ba16 459 */
ykuroda 0:13a5d365ba16 460 template<typename MatrixType>
ykuroda 0:13a5d365ba16 461 struct tridiagonalization_inplace_selector<MatrixType,3,false>
ykuroda 0:13a5d365ba16 462 {
ykuroda 0:13a5d365ba16 463 typedef typename MatrixType::Scalar Scalar;
ykuroda 0:13a5d365ba16 464 typedef typename MatrixType::RealScalar RealScalar;
ykuroda 0:13a5d365ba16 465
ykuroda 0:13a5d365ba16 466 template<typename DiagonalType, typename SubDiagonalType>
ykuroda 0:13a5d365ba16 467 static void run(MatrixType& mat, DiagonalType& diag, SubDiagonalType& subdiag, bool extractQ)
ykuroda 0:13a5d365ba16 468 {
ykuroda 0:13a5d365ba16 469 using std::sqrt;
ykuroda 0:13a5d365ba16 470 diag[0] = mat(0,0);
ykuroda 0:13a5d365ba16 471 RealScalar v1norm2 = numext::abs2(mat(2,0));
ykuroda 0:13a5d365ba16 472 if(v1norm2 == RealScalar(0))
ykuroda 0:13a5d365ba16 473 {
ykuroda 0:13a5d365ba16 474 diag[1] = mat(1,1);
ykuroda 0:13a5d365ba16 475 diag[2] = mat(2,2);
ykuroda 0:13a5d365ba16 476 subdiag[0] = mat(1,0);
ykuroda 0:13a5d365ba16 477 subdiag[1] = mat(2,1);
ykuroda 0:13a5d365ba16 478 if (extractQ)
ykuroda 0:13a5d365ba16 479 mat.setIdentity();
ykuroda 0:13a5d365ba16 480 }
ykuroda 0:13a5d365ba16 481 else
ykuroda 0:13a5d365ba16 482 {
ykuroda 0:13a5d365ba16 483 RealScalar beta = sqrt(numext::abs2(mat(1,0)) + v1norm2);
ykuroda 0:13a5d365ba16 484 RealScalar invBeta = RealScalar(1)/beta;
ykuroda 0:13a5d365ba16 485 Scalar m01 = mat(1,0) * invBeta;
ykuroda 0:13a5d365ba16 486 Scalar m02 = mat(2,0) * invBeta;
ykuroda 0:13a5d365ba16 487 Scalar q = RealScalar(2)*m01*mat(2,1) + m02*(mat(2,2) - mat(1,1));
ykuroda 0:13a5d365ba16 488 diag[1] = mat(1,1) + m02*q;
ykuroda 0:13a5d365ba16 489 diag[2] = mat(2,2) - m02*q;
ykuroda 0:13a5d365ba16 490 subdiag[0] = beta;
ykuroda 0:13a5d365ba16 491 subdiag[1] = mat(2,1) - m01 * q;
ykuroda 0:13a5d365ba16 492 if (extractQ)
ykuroda 0:13a5d365ba16 493 {
ykuroda 0:13a5d365ba16 494 mat << 1, 0, 0,
ykuroda 0:13a5d365ba16 495 0, m01, m02,
ykuroda 0:13a5d365ba16 496 0, m02, -m01;
ykuroda 0:13a5d365ba16 497 }
ykuroda 0:13a5d365ba16 498 }
ykuroda 0:13a5d365ba16 499 }
ykuroda 0:13a5d365ba16 500 };
ykuroda 0:13a5d365ba16 501
ykuroda 0:13a5d365ba16 502 /** \internal
ykuroda 0:13a5d365ba16 503 * Trivial specialization for 1x1 matrices
ykuroda 0:13a5d365ba16 504 */
ykuroda 0:13a5d365ba16 505 template<typename MatrixType, bool IsComplex>
ykuroda 0:13a5d365ba16 506 struct tridiagonalization_inplace_selector<MatrixType,1,IsComplex>
ykuroda 0:13a5d365ba16 507 {
ykuroda 0:13a5d365ba16 508 typedef typename MatrixType::Scalar Scalar;
ykuroda 0:13a5d365ba16 509
ykuroda 0:13a5d365ba16 510 template<typename DiagonalType, typename SubDiagonalType>
ykuroda 0:13a5d365ba16 511 static void run(MatrixType& mat, DiagonalType& diag, SubDiagonalType&, bool extractQ)
ykuroda 0:13a5d365ba16 512 {
ykuroda 0:13a5d365ba16 513 diag(0,0) = numext::real(mat(0,0));
ykuroda 0:13a5d365ba16 514 if(extractQ)
ykuroda 0:13a5d365ba16 515 mat(0,0) = Scalar(1);
ykuroda 0:13a5d365ba16 516 }
ykuroda 0:13a5d365ba16 517 };
ykuroda 0:13a5d365ba16 518
ykuroda 0:13a5d365ba16 519 /** \internal
ykuroda 0:13a5d365ba16 520 * \eigenvalues_module \ingroup Eigenvalues_Module
ykuroda 0:13a5d365ba16 521 *
ykuroda 0:13a5d365ba16 522 * \brief Expression type for return value of Tridiagonalization::matrixT()
ykuroda 0:13a5d365ba16 523 *
ykuroda 0:13a5d365ba16 524 * \tparam MatrixType type of underlying dense matrix
ykuroda 0:13a5d365ba16 525 */
ykuroda 0:13a5d365ba16 526 template<typename MatrixType> struct TridiagonalizationMatrixTReturnType
ykuroda 0:13a5d365ba16 527 : public ReturnByValue<TridiagonalizationMatrixTReturnType<MatrixType> >
ykuroda 0:13a5d365ba16 528 {
ykuroda 0:13a5d365ba16 529 typedef typename MatrixType::Index Index;
ykuroda 0:13a5d365ba16 530 public:
ykuroda 0:13a5d365ba16 531 /** \brief Constructor.
ykuroda 0:13a5d365ba16 532 *
ykuroda 0:13a5d365ba16 533 * \param[in] mat The underlying dense matrix
ykuroda 0:13a5d365ba16 534 */
ykuroda 0:13a5d365ba16 535 TridiagonalizationMatrixTReturnType(const MatrixType& mat) : m_matrix(mat) { }
ykuroda 0:13a5d365ba16 536
ykuroda 0:13a5d365ba16 537 template <typename ResultType>
ykuroda 0:13a5d365ba16 538 inline void evalTo(ResultType& result) const
ykuroda 0:13a5d365ba16 539 {
ykuroda 0:13a5d365ba16 540 result.setZero();
ykuroda 0:13a5d365ba16 541 result.template diagonal<1>() = m_matrix.template diagonal<-1>().conjugate();
ykuroda 0:13a5d365ba16 542 result.diagonal() = m_matrix.diagonal();
ykuroda 0:13a5d365ba16 543 result.template diagonal<-1>() = m_matrix.template diagonal<-1>();
ykuroda 0:13a5d365ba16 544 }
ykuroda 0:13a5d365ba16 545
ykuroda 0:13a5d365ba16 546 Index rows() const { return m_matrix.rows(); }
ykuroda 0:13a5d365ba16 547 Index cols() const { return m_matrix.cols(); }
ykuroda 0:13a5d365ba16 548
ykuroda 0:13a5d365ba16 549 protected:
ykuroda 0:13a5d365ba16 550 typename MatrixType::Nested m_matrix;
ykuroda 0:13a5d365ba16 551 };
ykuroda 0:13a5d365ba16 552
ykuroda 0:13a5d365ba16 553 } // end namespace internal
ykuroda 0:13a5d365ba16 554
ykuroda 0:13a5d365ba16 555 } // end namespace Eigen
ykuroda 0:13a5d365ba16 556
ykuroda 0:13a5d365ba16 557 #endif // EIGEN_TRIDIAGONALIZATION_H