From 2840ac7e948ecb3c7b19ba8f581f829a4a4e1fea Mon Sep 17 00:00:00 2001 From: Benoit Jacob Date: Wed, 28 Oct 2009 18:19:29 -0400 Subject: big huge changes, so i dont remember everything. * renaming, e.g. LU ---> FullPivLU * split tests framework: more robust, e.g. dont generate empty tests if a number is skipped * make all remaining tests use that splitting, as needed. * Fix 4x4 inversion (see stable branch) * Transform::inverse() and geo_transform test : adapt to new inverse() API, it was also trying to instantiate inverse() for 3x4 matrices. * CMakeLists: more robust regexp to parse the version number * misc fixes in unit tests --- Eigen/src/LU/Determinant.h | 2 +- Eigen/src/LU/FullPivLU.h | 753 ++++++++++++++++++++++++++++++++++++++++++++ Eigen/src/LU/Inverse.h | 47 +-- Eigen/src/LU/LU.h | 753 -------------------------------------------- Eigen/src/LU/PartialLU.h | 478 ---------------------------- Eigen/src/LU/PartialPivLU.h | 493 +++++++++++++++++++++++++++++ 6 files changed, 1275 insertions(+), 1251 deletions(-) create mode 100644 Eigen/src/LU/FullPivLU.h delete mode 100644 Eigen/src/LU/LU.h delete mode 100644 Eigen/src/LU/PartialLU.h create mode 100644 Eigen/src/LU/PartialPivLU.h (limited to 'Eigen/src/LU') diff --git a/Eigen/src/LU/Determinant.h b/Eigen/src/LU/Determinant.h index b587065ed..8870d9f20 100644 --- a/Eigen/src/LU/Determinant.h +++ b/Eigen/src/LU/Determinant.h @@ -53,7 +53,7 @@ template::Scalar run(const Derived& m) { - return m.partialLu().determinant(); + return m.partialPivLu().determinant(); } }; diff --git a/Eigen/src/LU/FullPivLU.h b/Eigen/src/LU/FullPivLU.h new file mode 100644 index 000000000..8743dac92 --- /dev/null +++ b/Eigen/src/LU/FullPivLU.h @@ -0,0 +1,753 @@ +// This file is part of Eigen, a lightweight C++ template library +// for linear algebra. +// +// Copyright (C) 2006-2009 Benoit Jacob +// +// Eigen is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 3 of the License, or (at your option) any later version. +// +// Alternatively, you can redistribute it and/or +// modify it under the terms of the GNU General Public License as +// published by the Free Software Foundation; either version 2 of +// the License, or (at your option) any later version. +// +// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License and a copy of the GNU General Public License along with +// Eigen. If not, see . + +#ifndef EIGEN_LU_H +#define EIGEN_LU_H + +template struct ei_lu_solve_impl; +template struct ei_lu_kernel_impl; +template struct ei_lu_image_impl; + +/** \ingroup LU_Module + * + * \class FullPivLU + * + * \brief LU decomposition of a matrix with complete pivoting, and related features + * + * \param MatrixType the type of the matrix of which we are computing the LU decomposition + * + * This class represents a LU decomposition of any matrix, with complete pivoting: the matrix A + * is decomposed as A = PLUQ where L is unit-lower-triangular, U is upper-triangular, and P and Q + * are permutation matrices. This is a rank-revealing LU decomposition. The eigenvalues (diagonal + * coefficients) of U are sorted in such a way that any zeros are at the end. + * + * This decomposition provides the generic approach to solving systems of linear equations, computing + * the rank, invertibility, inverse, kernel, and determinant. + * + * This LU decomposition is very stable and well tested with large matrices. However there are use cases where the SVD + * decomposition is inherently more stable and/or flexible. For example, when computing the kernel of a matrix, + * working with the SVD allows to select the smallest singular values of the matrix, something that + * the LU decomposition doesn't see. + * + * The data of the LU decomposition can be directly accessed through the methods matrixLU(), + * permutationP(), permutationQ(). + * + * As an exemple, here is how the original matrix can be retrieved: + * \include class_FullPivLU.cpp + * Output: \verbinclude class_FullPivLU.out + * + * \sa MatrixBase::fullPivLu(), MatrixBase::determinant(), MatrixBase::inverse() + */ +template class FullPivLU +{ + public: + + typedef typename MatrixType::Scalar Scalar; + typedef typename NumTraits::Real RealScalar; + typedef Matrix IntRowVectorType; + typedef Matrix IntColVectorType; + typedef Matrix RowVectorType; + typedef Matrix ColVectorType; + + enum { MaxSmallDimAtCompileTime = EIGEN_ENUM_MIN( + MatrixType::MaxColsAtCompileTime, + MatrixType::MaxRowsAtCompileTime) + }; + + /** + * \brief Default Constructor. + * + * The default constructor is useful in cases in which the user intends to + * perform decompositions via LU::compute(const MatrixType&). + */ + FullPivLU(); + + /** Constructor. + * + * \param matrix the matrix of which to compute the LU decomposition. + * It is required to be nonzero. + */ + FullPivLU(const MatrixType& matrix); + + /** Computes the LU decomposition of the given matrix. + * + * \param matrix the matrix of which to compute the LU decomposition. + * It is required to be nonzero. + * + * \returns a reference to *this + */ + FullPivLU& compute(const MatrixType& matrix); + + /** \returns the LU decomposition matrix: the upper-triangular part is U, the + * unit-lower-triangular part is L (at least for square matrices; in the non-square + * case, special care is needed, see the documentation of class FullPivLU). + * + * \sa matrixL(), matrixU() + */ + inline const MatrixType& matrixLU() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return m_lu; + } + + /** \returns the number of nonzero pivots in the LU decomposition. + * Here nonzero is meant in the exact sense, not in a fuzzy sense. + * So that notion isn't really intrinsically interesting, but it is + * still useful when implementing algorithms. + * + * \sa rank() + */ + inline int nonzeroPivots() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return m_nonzero_pivots; + } + + /** \returns the absolute value of the biggest pivot, i.e. the biggest + * diagonal coefficient of U. + */ + RealScalar maxPivot() const { return m_maxpivot; } + + /** \returns a vector of integers, whose size is the number of rows of the matrix being decomposed, + * representing the P permutation i.e. the permutation of the rows. For its precise meaning, + * see the examples given in the documentation of class FullPivLU. + * + * \sa permutationQ() + */ + inline const IntColVectorType& permutationP() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return m_p; + } + + /** \returns a vector of integers, whose size is the number of columns of the matrix being + * decomposed, representing the Q permutation i.e. the permutation of the columns. + * For its precise meaning, see the examples given in the documentation of class FullPivLU. + * + * \sa permutationP() + */ + inline const IntRowVectorType& permutationQ() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return m_q; + } + + /** \returns the kernel of the matrix, also called its null-space. The columns of the returned matrix + * will form a basis of the kernel. + * + * \note If the kernel has dimension zero, then the returned matrix is a column-vector filled with zeros. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + * + * Example: \include FullPivLU_kernel.cpp + * Output: \verbinclude FullPivLU_kernel.out + * + * \sa image() + */ + inline const ei_lu_kernel_impl kernel() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return ei_lu_kernel_impl(*this); + } + + /** \returns the image of the matrix, also called its column-space. The columns of the returned matrix + * will form a basis of the kernel. + * + * \param originalMatrix the original matrix, of which *this is the LU decomposition. + * The reason why it is needed to pass it here, is that this allows + * a large optimization, as otherwise this method would need to reconstruct it + * from the LU decomposition. + * + * \note If the image has dimension zero, then the returned matrix is a column-vector filled with zeros. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + * + * Example: \include FullPivLU_image.cpp + * Output: \verbinclude FullPivLU_image.out + * + * \sa kernel() + */ + template + inline const ei_lu_image_impl + image(const MatrixBase& originalMatrix) const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return ei_lu_image_impl(*this, originalMatrix.derived()); + } + + /** This method returns a solution x to the equation Ax=b, where A is the matrix of which + * *this is the LU decomposition. + * + * \param b the right-hand-side of the equation to solve. Can be a vector or a matrix, + * the only requirement in order for the equation to make sense is that + * b.rows()==A.rows(), where A is the matrix of which *this is the LU decomposition. + * + * \returns a solution. + * + * \note_about_checking_solutions + * + * \note_about_arbitrary_choice_of_solution + * \note_about_using_kernel_to_study_multiple_solutions + * + * Example: \include FullPivLU_solve.cpp + * Output: \verbinclude FullPivLU_solve.out + * + * \sa TriangularView::solve(), kernel(), inverse() + */ + template + inline const ei_lu_solve_impl + solve(const MatrixBase& b) const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return ei_lu_solve_impl(*this, b.derived()); + } + + /** \returns the determinant of the matrix of which + * *this is the LU decomposition. It has only linear complexity + * (that is, O(n) where n is the dimension of the square matrix) + * as the LU decomposition has already been computed. + * + * \note This is only for square matrices. + * + * \note For fixed-size matrices of size up to 4, MatrixBase::determinant() offers + * optimized paths. + * + * \warning a determinant can be very big or small, so for matrices + * of large enough dimension, there is a risk of overflow/underflow. + * + * \sa MatrixBase::determinant() + */ + typename ei_traits::Scalar determinant() const; + + /** Allows to prescribe a threshold to be used by certain methods, such as rank(), + * who need to determine when pivots are to be considered nonzero. This is not used for the + * LU decomposition itself. + * + * When it needs to get the threshold value, Eigen calls threshold(). By default, this calls + * defaultThreshold(). Once you have called the present method setThreshold(const RealScalar&), + * your value is used instead. + * + * \param threshold The new value to use as the threshold. + * + * A pivot will be considered nonzero if its absolute value is strictly greater than + * \f$ \vert pivot \vert \leqslant threshold \times \vert maxpivot \vert \f$ + * where maxpivot is the biggest pivot. + * + * If you want to come back to the default behavior, call setThreshold(Default_t) + */ + FullPivLU& setThreshold(const RealScalar& threshold) + { + m_usePrescribedThreshold = true; + m_prescribedThreshold = threshold; + } + + /** Allows to come back to the default behavior, letting Eigen use its default formula for + * determining the threshold. + * + * You should pass the special object Eigen::Default as parameter here. + * \code lu.setThreshold(Eigen::Default); \endcode + * + * See the documentation of setThreshold(const RealScalar&). + */ + FullPivLU& setThreshold(Default_t) + { + m_usePrescribedThreshold = false; + } + + /** Returns the threshold that will be used by certain methods such as rank(). + * + * See the documentation of setThreshold(const RealScalar&). + */ + RealScalar threshold() const + { + ei_assert(m_isInitialized || m_usePrescribedThreshold); + return m_usePrescribedThreshold ? m_prescribedThreshold + // this formula comes from experimenting (see "LU precision tuning" thread on the list) + // and turns out to be identical to Higham's formula used already in LDLt. + : epsilon() * m_lu.diagonalSize(); + } + + /** \returns the rank of the matrix of which *this is the LU decomposition. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + */ + inline int rank() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + RealScalar premultiplied_threshold = ei_abs(m_maxpivot) * threshold(); + int result = 0; + for(int i = 0; i < m_nonzero_pivots; ++i) + result += (ei_abs(m_lu.coeff(i,i)) > premultiplied_threshold); + return result; + } + + /** \returns the dimension of the kernel of the matrix of which *this is the LU decomposition. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + */ + inline int dimensionOfKernel() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return m_lu.cols() - rank(); + } + + /** \returns true if the matrix of which *this is the LU decomposition represents an injective + * linear map, i.e. has trivial kernel; false otherwise. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + */ + inline bool isInjective() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return rank() == m_lu.cols(); + } + + /** \returns true if the matrix of which *this is the LU decomposition represents a surjective + * linear map; false otherwise. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + */ + inline bool isSurjective() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return rank() == m_lu.rows(); + } + + /** \returns true if the matrix of which *this is the LU decomposition is invertible. + * + * \note This method has to determine which pivots should be considered nonzero. + * For that, it uses the threshold value that you can control by calling + * setThreshold(const RealScalar&). + */ + inline bool isInvertible() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return isInjective() && (m_lu.rows() == m_lu.cols()); + } + + /** \returns the inverse of the matrix of which *this is the LU decomposition. + * + * \note If this matrix is not invertible, the returned matrix has undefined coefficients. + * Use isInvertible() to first determine whether this matrix is invertible. + * + * \sa MatrixBase::inverse() + */ + inline const ei_lu_solve_impl > inverse() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + ei_assert(m_lu.rows() == m_lu.cols() && "You can't take the inverse of a non-square matrix!"); + return ei_lu_solve_impl > + (*this, MatrixType::Identity(m_lu.rows(), m_lu.cols()).nestByValue()); + } + + protected: + MatrixType m_lu; + IntColVectorType m_p; + IntRowVectorType m_q; + int m_det_pq, m_nonzero_pivots; + RealScalar m_maxpivot, m_prescribedThreshold; + bool m_isInitialized, m_usePrescribedThreshold; +}; + +template +FullPivLU::FullPivLU() + : m_isInitialized(false), m_usePrescribedThreshold(false) +{ +} + +template +FullPivLU::FullPivLU(const MatrixType& matrix) + : m_isInitialized(false), m_usePrescribedThreshold(false) +{ + compute(matrix); +} + +template +FullPivLU& FullPivLU::compute(const MatrixType& matrix) +{ + m_isInitialized = true; + m_lu = matrix; + m_p.resize(matrix.rows()); + m_q.resize(matrix.cols()); + + const int size = matrix.diagonalSize(); + const int rows = matrix.rows(); + const int cols = matrix.cols(); + + // will store the transpositions, before we accumulate them at the end. + // can't accumulate on-the-fly because that will be done in reverse order for the rows. + IntColVectorType rows_transpositions(matrix.rows()); + IntRowVectorType cols_transpositions(matrix.cols()); + int number_of_transpositions = 0; // number of NONTRIVIAL transpositions, i.e. rows_transpositions[i]!=i + + m_nonzero_pivots = size; // the generic case is that in which all pivots are nonzero (invertible case) + m_maxpivot = RealScalar(0); + for(int k = 0; k < size; ++k) + { + // First, we need to find the pivot. + + // biggest coefficient in the remaining bottom-right corner (starting at row k, col k) + int row_of_biggest_in_corner, col_of_biggest_in_corner; + RealScalar biggest_in_corner; + biggest_in_corner = m_lu.corner(Eigen::BottomRight, rows-k, cols-k) + .cwise().abs() + .maxCoeff(&row_of_biggest_in_corner, &col_of_biggest_in_corner); + row_of_biggest_in_corner += k; // correct the values! since they were computed in the corner, + col_of_biggest_in_corner += k; // need to add k to them. + + // if the pivot (hence the corner) is exactly zero, terminate to avoid generating nan/inf values + if(biggest_in_corner == RealScalar(0)) + { + // before exiting, make sure to initialize the still uninitialized row_transpositions + // in a sane state without destroying what we already have. + m_nonzero_pivots = k; + for(int i = k; i < size; i++) + { + rows_transpositions.coeffRef(i) = i; + cols_transpositions.coeffRef(i) = i; + } + break; + } + + if(biggest_in_corner > m_maxpivot) m_maxpivot = biggest_in_corner; + + // Now that we've found the pivot, we need to apply the row/col swaps to + // bring it to the location (k,k). + + rows_transpositions.coeffRef(k) = row_of_biggest_in_corner; + cols_transpositions.coeffRef(k) = col_of_biggest_in_corner; + if(k != row_of_biggest_in_corner) { + m_lu.row(k).swap(m_lu.row(row_of_biggest_in_corner)); + ++number_of_transpositions; + } + if(k != col_of_biggest_in_corner) { + m_lu.col(k).swap(m_lu.col(col_of_biggest_in_corner)); + ++number_of_transpositions; + } + + // Now that the pivot is at the right location, we update the remaining + // bottom-right corner by Gaussian elimination. + + if(k= 0; --k) + std::swap(m_p.coeffRef(k), m_p.coeffRef(rows_transpositions.coeff(k))); + + for(int k = 0; k < matrix.cols(); ++k) m_q.coeffRef(k) = k; + for(int k = 0; k < size; ++k) + std::swap(m_q.coeffRef(k), m_q.coeffRef(cols_transpositions.coeff(k))); + + m_det_pq = (number_of_transpositions%2) ? -1 : 1; + return *this; +} + +template +typename ei_traits::Scalar FullPivLU::determinant() const +{ + ei_assert(m_isInitialized && "LU is not initialized."); + ei_assert(m_lu.rows() == m_lu.cols() && "You can't take the determinant of a non-square matrix!"); + return Scalar(m_det_pq) * m_lu.diagonal().prod(); +} + +/********* Implementation of kernel() **************************************************/ + +template +struct ei_traits > +{ + typedef Matrix< + typename MatrixType::Scalar, + MatrixType::ColsAtCompileTime, // the number of rows in the "kernel matrix" + // is the number of cols of the original matrix + // so that the product "matrix * kernel = zero" makes sense + Dynamic, // we don't know at compile-time the dimension of the kernel + MatrixType::Options, + MatrixType::MaxColsAtCompileTime, // see explanation for 2nd template parameter + MatrixType::MaxColsAtCompileTime // the kernel is a subspace of the domain space, + // whose dimension is the number of columns of the original matrix + > ReturnMatrixType; +}; + +template +struct ei_lu_kernel_impl : public ReturnByValue > +{ + typedef FullPivLU LUType; + typedef typename MatrixType::Scalar Scalar; + typedef typename MatrixType::RealScalar RealScalar; + const LUType& m_lu; + int m_rank, m_cols; + + ei_lu_kernel_impl(const LUType& lu) + : m_lu(lu), + m_rank(lu.rank()), + m_cols(m_rank==lu.matrixLU().cols() ? 1 : lu.matrixLU().cols() - m_rank){} + + inline int rows() const { return m_lu.matrixLU().cols(); } + inline int cols() const { return m_cols; } + + template void evalTo(Dest& dst) const + { + const int cols = m_lu.matrixLU().cols(), dimker = cols - m_rank; + if(dimker == 0) + { + // The Kernel is just {0}, so it doesn't have a basis properly speaking, but let's + // avoid crashing/asserting as that depends on floating point calculations. Let's + // just return a single column vector filled with zeros. + dst.setZero(); + return; + } + + /* Let us use the following lemma: + * + * Lemma: If the matrix A has the LU decomposition PAQ = LU, + * then Ker A = Q(Ker U). + * + * Proof: trivial: just keep in mind that P, Q, L are invertible. + */ + + /* Thus, all we need to do is to compute Ker U, and then apply Q. + * + * U is upper triangular, with eigenvalues sorted so that any zeros appear at the end. + * Thus, the diagonal of U ends with exactly + * m_dimKer zero's. Let us use that to construct dimKer linearly + * independent vectors in Ker U. + */ + + Matrix pivots(m_rank); + RealScalar premultiplied_threshold = m_lu.maxPivot() * m_lu.threshold(); + int p = 0; + for(int i = 0; i < m_lu.nonzeroPivots(); ++i) + if(ei_abs(m_lu.matrixLU().coeff(i,i)) > premultiplied_threshold) + pivots.coeffRef(p++) = i; + ei_assert(p == m_rank && "You hit a bug in Eigen! Please report (backtrace and matrix)!"); + + // we construct a temporaty trapezoid matrix m, by taking the U matrix and + // permuting the rows and cols to bring the nonnegligible pivots to the top of + // the main diagonal. We need that to be able to apply our triangular solvers. + // FIXME when we get triangularView-for-rectangular-matrices, this can be simplified + Matrix + m(m_lu.matrixLU().block(0, 0, m_rank, cols)); + for(int i = 0; i < m_rank; ++i) + { + if(i) m.row(i).start(i).setZero(); + m.row(i).end(cols-i) = m_lu.matrixLU().row(pivots.coeff(i)).end(cols-i); + } + m.block(0, 0, m_rank, m_rank).template triangularView().setZero(); + for(int i = 0; i < m_rank; ++i) + m.col(i).swap(m.col(pivots.coeff(i))); + + // ok, we have our trapezoid matrix, we can apply the triangular solver. + // notice that the math behind this suggests that we should apply this to the + // negative of the RHS, but for performance we just put the negative sign elsewhere, see below. + m.corner(TopLeft, m_rank, m_rank) + .template triangularView().solveInPlace( + m.corner(TopRight, m_rank, dimker) + ); + + // now we must undo the column permutation that we had applied! + for(int i = m_rank-1; i >= 0; --i) + m.col(i).swap(m.col(pivots.coeff(i))); + + // see the negative sign in the next line, that's what we were talking about above. + for(int i = 0; i < m_rank; ++i) dst.row(m_lu.permutationQ().coeff(i)) = -m.row(i).end(dimker); + for(int i = m_rank; i < cols; ++i) dst.row(m_lu.permutationQ().coeff(i)).setZero(); + for(int k = 0; k < dimker; ++k) dst.coeffRef(m_lu.permutationQ().coeff(m_rank+k), k) = Scalar(1); + } +}; + +/***** Implementation of image() *****************************************************/ + +template +struct ei_traits > +{ + typedef Matrix< + typename MatrixType::Scalar, + MatrixType::RowsAtCompileTime, // the image is a subspace of the destination space, whose + // dimension is the number of rows of the original matrix + Dynamic, // we don't know at compile time the dimension of the image (the rank) + MatrixType::Options, + MatrixType::MaxRowsAtCompileTime, // the image matrix will consist of columns from the original matrix, + MatrixType::MaxColsAtCompileTime // so it has the same number of rows and at most as many columns. + > ReturnMatrixType; +}; + +template +struct ei_lu_image_impl : public ReturnByValue > +{ + typedef FullPivLU LUType; + typedef typename MatrixType::RealScalar RealScalar; + const LUType& m_lu; + int m_rank, m_cols; + const MatrixType& m_originalMatrix; + + ei_lu_image_impl(const LUType& lu, const MatrixType& originalMatrix) + : m_lu(lu), m_rank(lu.rank()), + m_cols(m_rank == 0 ? 1 : m_rank), + m_originalMatrix(originalMatrix) {} + + inline int rows() const { return m_lu.matrixLU().rows(); } + inline int cols() const { return m_cols; } + + template void evalTo(Dest& dst) const + { + if(m_rank == 0) + { + // The Image is just {0}, so it doesn't have a basis properly speaking, but let's + // avoid crashing/asserting as that depends on floating point calculations. Let's + // just return a single column vector filled with zeros. + dst.setZero(); + return; + } + + Matrix pivots(m_rank); + RealScalar premultiplied_threshold = m_lu.maxPivot() * m_lu.threshold(); + int p = 0; + for(int i = 0; i < m_lu.nonzeroPivots(); ++i) + if(ei_abs(m_lu.matrixLU().coeff(i,i)) > premultiplied_threshold) + pivots.coeffRef(p++) = i; + ei_assert(p == m_rank && "You hit a bug in Eigen! Please report (backtrace and matrix)!"); + + for(int i = 0; i < m_rank; ++i) + dst.col(i) = m_originalMatrix.col(m_lu.permutationQ().coeff(pivots.coeff(i))); + } +}; + +/***** Implementation of solve() *****************************************************/ + +template +struct ei_traits > +{ + typedef Matrix ReturnMatrixType; +}; + +template +struct ei_lu_solve_impl : public ReturnByValue > +{ + typedef typename ei_cleantype::type RhsNested; + typedef FullPivLU LUType; + const LUType& m_lu; + const typename Rhs::Nested m_rhs; + + ei_lu_solve_impl(const LUType& lu, const Rhs& rhs) + : m_lu(lu), m_rhs(rhs) + {} + + inline int rows() const { return m_lu.matrixLU().cols(); } + inline int cols() const { return m_rhs.cols(); } + + template void evalTo(Dest& dst) const + { + /* The decomposition PAQ = LU can be rewritten as A = P^{-1} L U Q^{-1}. + * So we proceed as follows: + * Step 1: compute c = P * rhs. + * Step 2: replace c by the solution x to Lx = c. Exists because L is invertible. + * Step 3: replace c by the solution x to Ux = c. May or may not exist. + * Step 4: result = Q * c; + */ + + const int rows = m_lu.matrixLU().rows(), + cols = m_lu.matrixLU().cols(), + nonzero_pivots = m_lu.nonzeroPivots(); + ei_assert(m_rhs.rows() == rows); + const int smalldim = std::min(rows, cols); + + if(nonzero_pivots == 0) + { + dst.setZero(); + return; + } + + typename Rhs::PlainMatrixType c(m_rhs.rows(), m_rhs.cols()); + + // Step 1 + for(int i = 0; i < rows; ++i) + c.row(m_lu.permutationP().coeff(i)) = m_rhs.row(i); + + // Step 2 + m_lu.matrixLU() + .corner(Eigen::TopLeft,smalldim,smalldim) + .template triangularView() + .solveInPlace(c.corner(Eigen::TopLeft, smalldim, c.cols())); + if(rows>cols) + { + c.corner(Eigen::BottomLeft, rows-cols, c.cols()) + -= m_lu.matrixLU().corner(Eigen::BottomLeft, rows-cols, cols) + * c.corner(Eigen::TopLeft, cols, c.cols()); + } + + // Step 3 + m_lu.matrixLU() + .corner(TopLeft, nonzero_pivots, nonzero_pivots) + .template triangularView() + .solveInPlace(c.corner(TopLeft, nonzero_pivots, c.cols())); + + // Step 4 + for(int i = 0; i < nonzero_pivots; ++i) + dst.row(m_lu.permutationQ().coeff(i)) = c.row(i); + for(int i = nonzero_pivots; i < m_lu.matrixLU().cols(); ++i) + dst.row(m_lu.permutationQ().coeff(i)).setZero(); + } +}; + +/******* MatrixBase methods *****************************************************************/ + +/** \lu_module + * + * \return the full-pivoting LU decomposition of \c *this. + * + * \sa class FullPivLU + */ +template +inline const FullPivLU::PlainMatrixType> +MatrixBase::fullPivLu() const +{ + return FullPivLU(eval()); +} + +#endif // EIGEN_LU_H diff --git a/Eigen/src/LU/Inverse.h b/Eigen/src/LU/Inverse.h index a168d58cd..306b5f60a 100644 --- a/Eigen/src/LU/Inverse.h +++ b/Eigen/src/LU/Inverse.h @@ -34,7 +34,7 @@ struct ei_compute_inverse { static inline void run(const MatrixType& matrix, ResultType& result) { - result = matrix.partialLu().inverse(); + result = matrix.partialPivLu().inverse(); } }; @@ -232,22 +232,31 @@ struct ei_compute_inverse typename MatrixType::PlainMatrixType matrix(_matrix); // let's extract from the 2 first colums a 2x2 block whose determinant is as big as possible. - int good_row0=0, good_row1=1; - RealScalar good_absdet(-1); - // this double for loop shouldn't be too costly: only 6 iterations - for(int row0=0; row0<4; ++row0) { - for(int row1=row0+1; row1<4; ++row1) - { - RealScalar absdet = ei_abs(matrix.coeff(row0,0)*matrix.coeff(row1,1) - - matrix.coeff(row0,1)*matrix.coeff(row1,0)); - if(absdet > good_absdet) - { - good_absdet = absdet; - good_row0 = row0; - good_row1 = row1; - } - } - } + int good_row0, good_row1, good_i; + Matrix absdet; + + // any 2x2 block with determinant above this threshold will be considered good enough + RealScalar d = (matrix.col(0).squaredNorm()+matrix.col(1).squaredNorm()) * RealScalar(1e-2); + #define ei_inv_size4_helper_macro(i,row0,row1) \ + absdet[i] = ei_abs(matrix.coeff(row0,0)*matrix.coeff(row1,1) \ + - matrix.coeff(row0,1)*matrix.coeff(row1,0)); \ + if(absdet[i] > d) { good_row0=row0; good_row1=row1; goto good; } + ei_inv_size4_helper_macro(0,0,1) + ei_inv_size4_helper_macro(1,0,2) + ei_inv_size4_helper_macro(2,0,3) + ei_inv_size4_helper_macro(3,1,2) + ei_inv_size4_helper_macro(4,1,3) + ei_inv_size4_helper_macro(5,2,3) + + // no 2x2 block has determinant bigger than the threshold. So just take the one that + // has the biggest determinant + absdet.maxCoeff(&good_i); + good_row0 = good_i <= 2 ? 0 : good_i <= 4 ? 1 : 2; + good_row1 = good_i <= 2 ? good_i+1 : good_i <= 4 ? good_i-1 : 3; + + // now good_row0 and good_row1 are correctly set + good: + // do row permutations to move this 2x2 block to the top matrix.row(0).swap(matrix.row(good_row0)); matrix.row(1).swap(matrix.row(good_row1)); @@ -318,12 +327,12 @@ struct ei_inverse_impl : public ReturnByValue > * \returns the matrix inverse of this matrix. * * For small fixed sizes up to 4x4, this method uses ad-hoc methods (cofactors up to 3x3, Euler's trick for 4x4). - * In the general case, this method uses class PartialLU. + * In the general case, this method uses class PartialPivLU. * * \note This matrix must be invertible, otherwise the result is undefined. If you need an * invertibility check, do the following: * \li for fixed sizes up to 4x4, use computeInverseAndDetWithCheck(). - * \li for the general case, use class LU. + * \li for the general case, use class FullPivLU. * * Example: \include MatrixBase_inverse.cpp * Output: \verbinclude MatrixBase_inverse.out diff --git a/Eigen/src/LU/LU.h b/Eigen/src/LU/LU.h deleted file mode 100644 index 4792aaf07..000000000 --- a/Eigen/src/LU/LU.h +++ /dev/null @@ -1,753 +0,0 @@ -// This file is part of Eigen, a lightweight C++ template library -// for linear algebra. -// -// Copyright (C) 2006-2009 Benoit Jacob -// -// Eigen is free software; you can redistribute it and/or -// modify it under the terms of the GNU Lesser General Public -// License as published by the Free Software Foundation; either -// version 3 of the License, or (at your option) any later version. -// -// Alternatively, you can redistribute it and/or -// modify it under the terms of the GNU General Public License as -// published by the Free Software Foundation; either version 2 of -// the License, or (at your option) any later version. -// -// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY -// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the -// GNU General Public License for more details. -// -// You should have received a copy of the GNU Lesser General Public -// License and a copy of the GNU General Public License along with -// Eigen. If not, see . - -#ifndef EIGEN_LU_H -#define EIGEN_LU_H - -template struct ei_lu_solve_impl; -template struct ei_lu_kernel_impl; -template struct ei_lu_image_impl; - -/** \ingroup LU_Module - * - * \class LU - * - * \brief LU decomposition of a matrix with complete pivoting, and related features - * - * \param MatrixType the type of the matrix of which we are computing the LU decomposition - * - * This class represents a LU decomposition of any matrix, with complete pivoting: the matrix A - * is decomposed as A = PLUQ where L is unit-lower-triangular, U is upper-triangular, and P and Q - * are permutation matrices. This is a rank-revealing LU decomposition. The eigenvalues (diagonal - * coefficients) of U are sorted in such a way that any zeros are at the end. - * - * This decomposition provides the generic approach to solving systems of linear equations, computing - * the rank, invertibility, inverse, kernel, and determinant. - * - * This LU decomposition is very stable and well tested with large matrices. However there are use cases where the SVD - * decomposition is inherently more stable and/or flexible. For example, when computing the kernel of a matrix, - * working with the SVD allows to select the smallest singular values of the matrix, something that - * the LU decomposition doesn't see. - * - * The data of the LU decomposition can be directly accessed through the methods matrixLU(), - * permutationP(), permutationQ(). - * - * As an exemple, here is how the original matrix can be retrieved: - * \include class_LU.cpp - * Output: \verbinclude class_LU.out - * - * \sa MatrixBase::lu(), MatrixBase::determinant(), MatrixBase::inverse() - */ -template class LU -{ - public: - - typedef typename MatrixType::Scalar Scalar; - typedef typename NumTraits::Real RealScalar; - typedef Matrix IntRowVectorType; - typedef Matrix IntColVectorType; - typedef Matrix RowVectorType; - typedef Matrix ColVectorType; - - enum { MaxSmallDimAtCompileTime = EIGEN_ENUM_MIN( - MatrixType::MaxColsAtCompileTime, - MatrixType::MaxRowsAtCompileTime) - }; - - /** - * \brief Default Constructor. - * - * The default constructor is useful in cases in which the user intends to - * perform decompositions via LU::compute(const MatrixType&). - */ - LU(); - - /** Constructor. - * - * \param matrix the matrix of which to compute the LU decomposition. - * It is required to be nonzero. - */ - LU(const MatrixType& matrix); - - /** Computes the LU decomposition of the given matrix. - * - * \param matrix the matrix of which to compute the LU decomposition. - * It is required to be nonzero. - * - * \returns a reference to *this - */ - LU& compute(const MatrixType& matrix); - - /** \returns the LU decomposition matrix: the upper-triangular part is U, the - * unit-lower-triangular part is L (at least for square matrices; in the non-square - * case, special care is needed, see the documentation of class LU). - * - * \sa matrixL(), matrixU() - */ - inline const MatrixType& matrixLU() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return m_lu; - } - - /** \returns the number of nonzero pivots in the LU decomposition. - * Here nonzero is meant in the exact sense, not in a fuzzy sense. - * So that notion isn't really intrinsically interesting, but it is - * still useful when implementing algorithms. - * - * \sa rank() - */ - inline int nonzeroPivots() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return m_nonzero_pivots; - } - - /** \returns the absolute value of the biggest pivot, i.e. the biggest - * diagonal coefficient of U. - */ - RealScalar maxPivot() const { return m_maxpivot; } - - /** \returns a vector of integers, whose size is the number of rows of the matrix being decomposed, - * representing the P permutation i.e. the permutation of the rows. For its precise meaning, - * see the examples given in the documentation of class LU. - * - * \sa permutationQ() - */ - inline const IntColVectorType& permutationP() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return m_p; - } - - /** \returns a vector of integers, whose size is the number of columns of the matrix being - * decomposed, representing the Q permutation i.e. the permutation of the columns. - * For its precise meaning, see the examples given in the documentation of class LU. - * - * \sa permutationP() - */ - inline const IntRowVectorType& permutationQ() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return m_q; - } - - /** \returns the kernel of the matrix, also called its null-space. The columns of the returned matrix - * will form a basis of the kernel. - * - * \note If the kernel has dimension zero, then the returned matrix is a column-vector filled with zeros. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - * - * Example: \include LU_kernel.cpp - * Output: \verbinclude LU_kernel.out - * - * \sa image() - */ - inline const ei_lu_kernel_impl kernel() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return ei_lu_kernel_impl(*this); - } - - /** \returns the image of the matrix, also called its column-space. The columns of the returned matrix - * will form a basis of the kernel. - * - * \param originalMatrix the original matrix, of which *this is the LU decomposition. - * The reason why it is needed to pass it here, is that this allows - * a large optimization, as otherwise this method would need to reconstruct it - * from the LU decomposition. - * - * \note If the image has dimension zero, then the returned matrix is a column-vector filled with zeros. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - * - * Example: \include LU_image.cpp - * Output: \verbinclude LU_image.out - * - * \sa kernel() - */ - template - inline const ei_lu_image_impl - image(const MatrixBase& originalMatrix) const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return ei_lu_image_impl(*this, originalMatrix.derived()); - } - - /** This method returns a solution x to the equation Ax=b, where A is the matrix of which - * *this is the LU decomposition. - * - * \param b the right-hand-side of the equation to solve. Can be a vector or a matrix, - * the only requirement in order for the equation to make sense is that - * b.rows()==A.rows(), where A is the matrix of which *this is the LU decomposition. - * - * \returns a solution. - * - * \note_about_checking_solutions - * - * \note_about_arbitrary_choice_of_solution - * \note_about_using_kernel_to_study_multiple_solutions - * - * Example: \include LU_solve.cpp - * Output: \verbinclude LU_solve.out - * - * \sa TriangularView::solve(), kernel(), inverse() - */ - template - inline const ei_lu_solve_impl - solve(const MatrixBase& b) const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return ei_lu_solve_impl(*this, b.derived()); - } - - /** \returns the determinant of the matrix of which - * *this is the LU decomposition. It has only linear complexity - * (that is, O(n) where n is the dimension of the square matrix) - * as the LU decomposition has already been computed. - * - * \note This is only for square matrices. - * - * \note For fixed-size matrices of size up to 4, MatrixBase::determinant() offers - * optimized paths. - * - * \warning a determinant can be very big or small, so for matrices - * of large enough dimension, there is a risk of overflow/underflow. - * - * \sa MatrixBase::determinant() - */ - typename ei_traits::Scalar determinant() const; - - /** Allows to prescribe a threshold to be used by certain methods, such as rank(), - * who need to determine when pivots are to be considered nonzero. This is not used for the - * LU decomposition itself. - * - * When it needs to get the threshold value, Eigen calls threshold(). By default, this calls - * defaultThreshold(). Once you have called the present method setThreshold(const RealScalar&), - * your value is used instead. - * - * \param threshold The new value to use as the threshold. - * - * A pivot will be considered nonzero if its absolute value is strictly greater than - * \f$ \vert pivot \vert \leqslant threshold \times \vert maxpivot \vert \f$ - * where maxpivot is the biggest pivot. - * - * If you want to come back to the default behavior, call setThreshold(Default_t) - */ - LU& setThreshold(const RealScalar& threshold) - { - m_usePrescribedThreshold = true; - m_prescribedThreshold = threshold; - } - - /** Allows to come back to the default behavior, letting Eigen use its default formula for - * determining the threshold. - * - * You should pass the special object Eigen::Default as parameter here. - * \code lu.setThreshold(Eigen::Default); \endcode - * - * See the documentation of setThreshold(const RealScalar&). - */ - LU& setThreshold(Default_t) - { - m_usePrescribedThreshold = false; - } - - /** Returns the threshold that will be used by certain methods such as rank(). - * - * See the documentation of setThreshold(const RealScalar&). - */ - RealScalar threshold() const - { - ei_assert(m_isInitialized || m_usePrescribedThreshold); - return m_usePrescribedThreshold ? m_prescribedThreshold - // this formula comes from experimenting (see "LU precision tuning" thread on the list) - // and turns out to be identical to Higham's formula used already in LDLt. - : epsilon() * m_lu.diagonalSize(); - } - - /** \returns the rank of the matrix of which *this is the LU decomposition. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - */ - inline int rank() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - RealScalar premultiplied_threshold = ei_abs(m_maxpivot) * threshold(); - int result = 0; - for(int i = 0; i < m_nonzero_pivots; ++i) - result += (ei_abs(m_lu.coeff(i,i)) > premultiplied_threshold); - return result; - } - - /** \returns the dimension of the kernel of the matrix of which *this is the LU decomposition. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - */ - inline int dimensionOfKernel() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return m_lu.cols() - rank(); - } - - /** \returns true if the matrix of which *this is the LU decomposition represents an injective - * linear map, i.e. has trivial kernel; false otherwise. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - */ - inline bool isInjective() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return rank() == m_lu.cols(); - } - - /** \returns true if the matrix of which *this is the LU decomposition represents a surjective - * linear map; false otherwise. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - */ - inline bool isSurjective() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return rank() == m_lu.rows(); - } - - /** \returns true if the matrix of which *this is the LU decomposition is invertible. - * - * \note This method has to determine which pivots should be considered nonzero. - * For that, it uses the threshold value that you can control by calling - * setThreshold(const RealScalar&). - */ - inline bool isInvertible() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return isInjective() && (m_lu.rows() == m_lu.cols()); - } - - /** \returns the inverse of the matrix of which *this is the LU decomposition. - * - * \note If this matrix is not invertible, the returned matrix has undefined coefficients. - * Use isInvertible() to first determine whether this matrix is invertible. - * - * \sa MatrixBase::inverse() - */ - inline const ei_lu_solve_impl > inverse() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - ei_assert(m_lu.rows() == m_lu.cols() && "You can't take the inverse of a non-square matrix!"); - return ei_lu_solve_impl > - (*this, MatrixType::Identity(m_lu.rows(), m_lu.cols()).nestByValue()); - } - - protected: - MatrixType m_lu; - IntColVectorType m_p; - IntRowVectorType m_q; - int m_det_pq, m_nonzero_pivots; - RealScalar m_maxpivot, m_prescribedThreshold; - bool m_isInitialized, m_usePrescribedThreshold; -}; - -template -LU::LU() - : m_isInitialized(false), m_usePrescribedThreshold(false) -{ -} - -template -LU::LU(const MatrixType& matrix) - : m_isInitialized(false), m_usePrescribedThreshold(false) -{ - compute(matrix); -} - -template -LU& LU::compute(const MatrixType& matrix) -{ - m_isInitialized = true; - m_lu = matrix; - m_p.resize(matrix.rows()); - m_q.resize(matrix.cols()); - - const int size = matrix.diagonalSize(); - const int rows = matrix.rows(); - const int cols = matrix.cols(); - - // will store the transpositions, before we accumulate them at the end. - // can't accumulate on-the-fly because that will be done in reverse order for the rows. - IntColVectorType rows_transpositions(matrix.rows()); - IntRowVectorType cols_transpositions(matrix.cols()); - int number_of_transpositions = 0; // number of NONTRIVIAL transpositions, i.e. rows_transpositions[i]!=i - - m_nonzero_pivots = size; // the generic case is that in which all pivots are nonzero (invertible case) - m_maxpivot = RealScalar(0); - for(int k = 0; k < size; ++k) - { - // First, we need to find the pivot. - - // biggest coefficient in the remaining bottom-right corner (starting at row k, col k) - int row_of_biggest_in_corner, col_of_biggest_in_corner; - RealScalar biggest_in_corner; - biggest_in_corner = m_lu.corner(Eigen::BottomRight, rows-k, cols-k) - .cwise().abs() - .maxCoeff(&row_of_biggest_in_corner, &col_of_biggest_in_corner); - row_of_biggest_in_corner += k; // correct the values! since they were computed in the corner, - col_of_biggest_in_corner += k; // need to add k to them. - - // if the pivot (hence the corner) is exactly zero, terminate to avoid generating nan/inf values - if(biggest_in_corner == RealScalar(0)) - { - // before exiting, make sure to initialize the still uninitialized row_transpositions - // in a sane state without destroying what we already have. - m_nonzero_pivots = k; - for(int i = k; i < size; i++) - { - rows_transpositions.coeffRef(i) = i; - cols_transpositions.coeffRef(i) = i; - } - break; - } - - if(biggest_in_corner > m_maxpivot) m_maxpivot = biggest_in_corner; - - // Now that we've found the pivot, we need to apply the row/col swaps to - // bring it to the location (k,k). - - rows_transpositions.coeffRef(k) = row_of_biggest_in_corner; - cols_transpositions.coeffRef(k) = col_of_biggest_in_corner; - if(k != row_of_biggest_in_corner) { - m_lu.row(k).swap(m_lu.row(row_of_biggest_in_corner)); - ++number_of_transpositions; - } - if(k != col_of_biggest_in_corner) { - m_lu.col(k).swap(m_lu.col(col_of_biggest_in_corner)); - ++number_of_transpositions; - } - - // Now that the pivot is at the right location, we update the remaining - // bottom-right corner by Gaussian elimination. - - if(k= 0; --k) - std::swap(m_p.coeffRef(k), m_p.coeffRef(rows_transpositions.coeff(k))); - - for(int k = 0; k < matrix.cols(); ++k) m_q.coeffRef(k) = k; - for(int k = 0; k < size; ++k) - std::swap(m_q.coeffRef(k), m_q.coeffRef(cols_transpositions.coeff(k))); - - m_det_pq = (number_of_transpositions%2) ? -1 : 1; - return *this; -} - -template -typename ei_traits::Scalar LU::determinant() const -{ - ei_assert(m_isInitialized && "LU is not initialized."); - ei_assert(m_lu.rows() == m_lu.cols() && "You can't take the determinant of a non-square matrix!"); - return Scalar(m_det_pq) * m_lu.diagonal().prod(); -} - -/********* Implementation of kernel() **************************************************/ - -template -struct ei_traits > -{ - typedef Matrix< - typename MatrixType::Scalar, - MatrixType::ColsAtCompileTime, // the number of rows in the "kernel matrix" - // is the number of cols of the original matrix - // so that the product "matrix * kernel = zero" makes sense - Dynamic, // we don't know at compile-time the dimension of the kernel - MatrixType::Options, - MatrixType::MaxColsAtCompileTime, // see explanation for 2nd template parameter - MatrixType::MaxColsAtCompileTime // the kernel is a subspace of the domain space, - // whose dimension is the number of columns of the original matrix - > ReturnMatrixType; -}; - -template -struct ei_lu_kernel_impl : public ReturnByValue > -{ - typedef LU LUType; - typedef typename MatrixType::Scalar Scalar; - typedef typename MatrixType::RealScalar RealScalar; - const LUType& m_lu; - int m_rank, m_cols; - - ei_lu_kernel_impl(const LUType& lu) - : m_lu(lu), - m_rank(lu.rank()), - m_cols(m_rank==lu.matrixLU().cols() ? 1 : lu.matrixLU().cols() - m_rank){} - - inline int rows() const { return m_lu.matrixLU().cols(); } - inline int cols() const { return m_cols; } - - template void evalTo(Dest& dst) const - { - const int cols = m_lu.matrixLU().cols(), dimker = cols - m_rank; - if(dimker == 0) - { - // The Kernel is just {0}, so it doesn't have a basis properly speaking, but let's - // avoid crashing/asserting as that depends on floating point calculations. Let's - // just return a single column vector filled with zeros. - dst.setZero(); - return; - } - - /* Let us use the following lemma: - * - * Lemma: If the matrix A has the LU decomposition PAQ = LU, - * then Ker A = Q(Ker U). - * - * Proof: trivial: just keep in mind that P, Q, L are invertible. - */ - - /* Thus, all we need to do is to compute Ker U, and then apply Q. - * - * U is upper triangular, with eigenvalues sorted so that any zeros appear at the end. - * Thus, the diagonal of U ends with exactly - * m_dimKer zero's. Let us use that to construct dimKer linearly - * independent vectors in Ker U. - */ - - Matrix pivots(m_rank); - RealScalar premultiplied_threshold = m_lu.maxPivot() * m_lu.threshold(); - int p = 0; - for(int i = 0; i < m_lu.nonzeroPivots(); ++i) - if(ei_abs(m_lu.matrixLU().coeff(i,i)) > premultiplied_threshold) - pivots.coeffRef(p++) = i; - ei_assert(p == m_rank && "You hit a bug in Eigen! Please report (backtrace and matrix)!"); - - // we construct a temporaty trapezoid matrix m, by taking the U matrix and - // permuting the rows and cols to bring the nonnegligible pivots to the top of - // the main diagonal. We need that to be able to apply our triangular solvers. - // FIXME when we get triangularView-for-rectangular-matrices, this can be simplified - Matrix - m(m_lu.matrixLU().block(0, 0, m_rank, cols)); - for(int i = 0; i < m_rank; ++i) - { - if(i) m.row(i).start(i).setZero(); - m.row(i).end(cols-i) = m_lu.matrixLU().row(pivots.coeff(i)).end(cols-i); - } - m.block(0, 0, m_rank, m_rank).template triangularView().setZero(); - for(int i = 0; i < m_rank; ++i) - m.col(i).swap(m.col(pivots.coeff(i))); - - // ok, we have our trapezoid matrix, we can apply the triangular solver. - // notice that the math behind this suggests that we should apply this to the - // negative of the RHS, but for performance we just put the negative sign elsewhere, see below. - m.corner(TopLeft, m_rank, m_rank) - .template triangularView().solveInPlace( - m.corner(TopRight, m_rank, dimker) - ); - - // now we must undo the column permutation that we had applied! - for(int i = m_rank-1; i >= 0; --i) - m.col(i).swap(m.col(pivots.coeff(i))); - - // see the negative sign in the next line, that's what we were talking about above. - for(int i = 0; i < m_rank; ++i) dst.row(m_lu.permutationQ().coeff(i)) = -m.row(i).end(dimker); - for(int i = m_rank; i < cols; ++i) dst.row(m_lu.permutationQ().coeff(i)).setZero(); - for(int k = 0; k < dimker; ++k) dst.coeffRef(m_lu.permutationQ().coeff(m_rank+k), k) = Scalar(1); - } -}; - -/***** Implementation of image() *****************************************************/ - -template -struct ei_traits > -{ - typedef Matrix< - typename MatrixType::Scalar, - MatrixType::RowsAtCompileTime, // the image is a subspace of the destination space, whose - // dimension is the number of rows of the original matrix - Dynamic, // we don't know at compile time the dimension of the image (the rank) - MatrixType::Options, - MatrixType::MaxRowsAtCompileTime, // the image matrix will consist of columns from the original matrix, - MatrixType::MaxColsAtCompileTime // so it has the same number of rows and at most as many columns. - > ReturnMatrixType; -}; - -template -struct ei_lu_image_impl : public ReturnByValue > -{ - typedef LU LUType; - typedef typename MatrixType::RealScalar RealScalar; - const LUType& m_lu; - int m_rank, m_cols; - const MatrixType& m_originalMatrix; - - ei_lu_image_impl(const LUType& lu, const MatrixType& originalMatrix) - : m_lu(lu), m_rank(lu.rank()), - m_cols(m_rank == 0 ? 1 : m_rank), - m_originalMatrix(originalMatrix) {} - - inline int rows() const { return m_lu.matrixLU().rows(); } - inline int cols() const { return m_cols; } - - template void evalTo(Dest& dst) const - { - if(m_rank == 0) - { - // The Image is just {0}, so it doesn't have a basis properly speaking, but let's - // avoid crashing/asserting as that depends on floating point calculations. Let's - // just return a single column vector filled with zeros. - dst.setZero(); - return; - } - - Matrix pivots(m_rank); - RealScalar premultiplied_threshold = m_lu.maxPivot() * m_lu.threshold(); - int p = 0; - for(int i = 0; i < m_lu.nonzeroPivots(); ++i) - if(ei_abs(m_lu.matrixLU().coeff(i,i)) > premultiplied_threshold) - pivots.coeffRef(p++) = i; - ei_assert(p == m_rank && "You hit a bug in Eigen! Please report (backtrace and matrix)!"); - - for(int i = 0; i < m_rank; ++i) - dst.col(i) = m_originalMatrix.col(m_lu.permutationQ().coeff(pivots.coeff(i))); - } -}; - -/***** Implementation of solve() *****************************************************/ - -template -struct ei_traits > -{ - typedef Matrix ReturnMatrixType; -}; - -template -struct ei_lu_solve_impl : public ReturnByValue > -{ - typedef typename ei_cleantype::type RhsNested; - typedef LU LUType; - const LUType& m_lu; - const typename Rhs::Nested m_rhs; - - ei_lu_solve_impl(const LUType& lu, const Rhs& rhs) - : m_lu(lu), m_rhs(rhs) - {} - - inline int rows() const { return m_lu.matrixLU().cols(); } - inline int cols() const { return m_rhs.cols(); } - - template void evalTo(Dest& dst) const - { - /* The decomposition PAQ = LU can be rewritten as A = P^{-1} L U Q^{-1}. - * So we proceed as follows: - * Step 1: compute c = P * rhs. - * Step 2: replace c by the solution x to Lx = c. Exists because L is invertible. - * Step 3: replace c by the solution x to Ux = c. May or may not exist. - * Step 4: result = Q * c; - */ - - const int rows = m_lu.matrixLU().rows(), - cols = m_lu.matrixLU().cols(), - nonzero_pivots = m_lu.nonzeroPivots(); - ei_assert(m_rhs.rows() == rows); - const int smalldim = std::min(rows, cols); - - if(nonzero_pivots == 0) - { - dst.setZero(); - return; - } - - typename Rhs::PlainMatrixType c(m_rhs.rows(), m_rhs.cols()); - - // Step 1 - for(int i = 0; i < rows; ++i) - c.row(m_lu.permutationP().coeff(i)) = m_rhs.row(i); - - // Step 2 - m_lu.matrixLU() - .corner(Eigen::TopLeft,smalldim,smalldim) - .template triangularView() - .solveInPlace(c.corner(Eigen::TopLeft, smalldim, c.cols())); - if(rows>cols) - { - c.corner(Eigen::BottomLeft, rows-cols, c.cols()) - -= m_lu.matrixLU().corner(Eigen::BottomLeft, rows-cols, cols) - * c.corner(Eigen::TopLeft, cols, c.cols()); - } - - // Step 3 - m_lu.matrixLU() - .corner(TopLeft, nonzero_pivots, nonzero_pivots) - .template triangularView() - .solveInPlace(c.corner(TopLeft, nonzero_pivots, c.cols())); - - // Step 4 - for(int i = 0; i < nonzero_pivots; ++i) - dst.row(m_lu.permutationQ().coeff(i)) = c.row(i); - for(int i = nonzero_pivots; i < m_lu.matrixLU().cols(); ++i) - dst.row(m_lu.permutationQ().coeff(i)).setZero(); - } -}; - -/******* MatrixBase methods *****************************************************************/ - -/** \lu_module - * - * \return the LU decomposition of \c *this. - * - * \sa class LU - */ -template -inline const LU::PlainMatrixType> -MatrixBase::lu() const -{ - return LU(eval()); -} - -#endif // EIGEN_LU_H diff --git a/Eigen/src/LU/PartialLU.h b/Eigen/src/LU/PartialLU.h deleted file mode 100644 index e8d21e5ad..000000000 --- a/Eigen/src/LU/PartialLU.h +++ /dev/null @@ -1,478 +0,0 @@ -// This file is part of Eigen, a lightweight C++ template library -// for linear algebra. -// -// Copyright (C) 2006-2009 Benoit Jacob -// Copyright (C) 2009 Gael Guennebaud -// -// Eigen is free software; you can redistribute it and/or -// modify it under the terms of the GNU Lesser General Public -// License as published by the Free Software Foundation; either -// version 3 of the License, or (at your option) any later version. -// -// Alternatively, you can redistribute it and/or -// modify it under the terms of the GNU General Public License as -// published by the Free Software Foundation; either version 2 of -// the License, or (at your option) any later version. -// -// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY -// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the -// GNU General Public License for more details. -// -// You should have received a copy of the GNU Lesser General Public -// License and a copy of the GNU General Public License along with -// Eigen. If not, see . - -#ifndef EIGEN_PARTIALLU_H -#define EIGEN_PARTIALLU_H - -template struct ei_partiallu_solve_impl; - -/** \ingroup LU_Module - * - * \class PartialLU - * - * \brief LU decomposition of a matrix with partial pivoting, and related features - * - * \param MatrixType the type of the matrix of which we are computing the LU decomposition - * - * This class represents a LU decomposition of a \b square \b invertible matrix, with partial pivoting: the matrix A - * is decomposed as A = PLU where L is unit-lower-triangular, U is upper-triangular, and P - * is a permutation matrix. - * - * Typically, partial pivoting LU decomposition is only considered numerically stable for square invertible - * matrices. Thus LAPACK's dgesv and dgesvx require the matrix to be square and invertible. The present class - * does the same. It will assert that the matrix is square, but it won't (actually it can't) check that the - * matrix is invertible: it is your task to check that you only use this decomposition on invertible matrices. - * - * The guaranteed safe alternative, working for all matrices, is the full pivoting LU decomposition, provided - * by class LU. - * - * This is \b not a rank-revealing LU decomposition. Many features are intentionally absent from this class, - * such as rank computation. If you need these features, use class LU. - * - * This LU decomposition is suitable to invert invertible matrices. It is what MatrixBase::inverse() uses - * in the general case. - * On the other hand, it is \b not suitable to determine whether a given matrix is invertible. - * - * The data of the LU decomposition can be directly accessed through the methods matrixLU(), permutationP(). - * - * \sa MatrixBase::partialLu(), MatrixBase::determinant(), MatrixBase::inverse(), MatrixBase::computeInverse(), class LU - */ -template class PartialLU -{ - public: - - typedef typename MatrixType::Scalar Scalar; - typedef typename NumTraits::Real RealScalar; - typedef Matrix IntRowVectorType; - typedef Matrix IntColVectorType; - typedef Matrix RowVectorType; - typedef Matrix ColVectorType; - - enum { MaxSmallDimAtCompileTime = EIGEN_ENUM_MIN( - MatrixType::MaxColsAtCompileTime, - MatrixType::MaxRowsAtCompileTime) - }; - - /** - * \brief Default Constructor. - * - * The default constructor is useful in cases in which the user intends to - * perform decompositions via PartialLU::compute(const MatrixType&). - */ - PartialLU(); - - /** Constructor. - * - * \param matrix the matrix of which to compute the LU decomposition. - * - * \warning The matrix should have full rank (e.g. if it's square, it should be invertible). - * If you need to deal with non-full rank, use class LU instead. - */ - PartialLU(const MatrixType& matrix); - - PartialLU& compute(const MatrixType& matrix); - - /** \returns the LU decomposition matrix: the upper-triangular part is U, the - * unit-lower-triangular part is L (at least for square matrices; in the non-square - * case, special care is needed, see the documentation of class LU). - * - * \sa matrixL(), matrixU() - */ - inline const MatrixType& matrixLU() const - { - ei_assert(m_isInitialized && "PartialLU is not initialized."); - return m_lu; - } - - /** \returns a vector of integers, whose size is the number of rows of the matrix being decomposed, - * representing the P permutation i.e. the permutation of the rows. For its precise meaning, - * see the examples given in the documentation of class LU. - */ - inline const IntColVectorType& permutationP() const - { - ei_assert(m_isInitialized && "PartialLU is not initialized."); - return m_p; - } - - /** This method returns a solution x to the equation Ax=b, where A is the matrix of which - * *this is the LU decomposition. - * - * \param b the right-hand-side of the equation to solve. Can be a vector or a matrix, - * the only requirement in order for the equation to make sense is that - * b.rows()==A.rows(), where A is the matrix of which *this is the LU decomposition. - * - * \returns the solution. - * - * Example: \include PartialLU_solve.cpp - * Output: \verbinclude PartialLU_solve.out - * - * Since this PartialLU class assumes anyway that the matrix A is invertible, the solution - * theoretically exists and is unique regardless of b. - * - * \note_about_checking_solutions - * - * \sa TriangularView::solve(), inverse(), computeInverse() - */ - template - inline const ei_partiallu_solve_impl - solve(const MatrixBase& b) const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return ei_partiallu_solve_impl(*this, b.derived()); - } - - /** \returns the inverse of the matrix of which *this is the LU decomposition. - * - * \warning The matrix being decomposed here is assumed to be invertible. If you need to check for - * invertibility, use class LU instead. - * - * \sa MatrixBase::inverse(), LU::inverse() - */ - inline const ei_partiallu_solve_impl > inverse() const - { - ei_assert(m_isInitialized && "LU is not initialized."); - return ei_partiallu_solve_impl > - (*this, MatrixType::Identity(m_lu.rows(), m_lu.cols()).nestByValue()); - } - - /** \returns the determinant of the matrix of which - * *this is the LU decomposition. It has only linear complexity - * (that is, O(n) where n is the dimension of the square matrix) - * as the LU decomposition has already been computed. - * - * \note For fixed-size matrices of size up to 4, MatrixBase::determinant() offers - * optimized paths. - * - * \warning a determinant can be very big or small, so for matrices - * of large enough dimension, there is a risk of overflow/underflow. - * - * \sa MatrixBase::determinant() - */ - typename ei_traits::Scalar determinant() const; - - protected: - MatrixType m_lu; - IntColVectorType m_p; - int m_det_p; - bool m_isInitialized; -}; - -template -PartialLU::PartialLU() - : m_lu(), - m_p(), - m_det_p(0), - m_isInitialized(false) -{ -} - -template -PartialLU::PartialLU(const MatrixType& matrix) - : m_lu(), - m_p(), - m_det_p(0), - m_isInitialized(false) -{ - compute(matrix); -} - - - -/** This is the blocked version of ei_lu_unblocked() */ -template -struct ei_partial_lu_impl -{ - // FIXME add a stride to Map, so that the following mapping becomes easier, - // another option would be to create an expression being able to automatically - // warp any Map, Matrix, and Block expressions as a unique type, but since that's exactly - // a Map + stride, why not adding a stride to Map, and convenient ctors from a Matrix, - // and Block. - typedef Map > MapLU; - typedef Block MatrixType; - typedef Block BlockType; - typedef typename MatrixType::RealScalar RealScalar; - - /** \internal performs the LU decomposition in-place of the matrix \a lu - * using an unblocked algorithm. - * - * In addition, this function returns the row transpositions in the - * vector \a row_transpositions which must have a size equal to the number - * of columns of the matrix \a lu, and an integer \a nb_transpositions - * which returns the actual number of transpositions. - * - * \returns false if some pivot is exactly zero, in which case the matrix is left with - * undefined coefficients (to avoid generating inf/nan values). Returns true - * otherwise. - */ - static bool unblocked_lu(MatrixType& lu, int* row_transpositions, int& nb_transpositions) - { - const int rows = lu.rows(); - const int size = std::min(lu.rows(),lu.cols()); - nb_transpositions = 0; - for(int k = 0; k < size; ++k) - { - int row_of_biggest_in_col; - RealScalar biggest_in_corner - = lu.col(k).end(rows-k).cwise().abs().maxCoeff(&row_of_biggest_in_col); - row_of_biggest_in_col += k; - - if(biggest_in_corner == 0) // the pivot is exactly zero: the matrix is singular - { - // end quickly, avoid generating inf/nan values. Although in this unblocked_lu case - // the result is still valid, there's no need to boast about it because - // the blocked_lu code can't guarantee the same. - // before exiting, make sure to initialize the still uninitialized row_transpositions - // in a sane state without destroying what we already have. - for(int i = k; i < size; i++) - row_transpositions[i] = i; - return false; - } - - row_transpositions[k] = row_of_biggest_in_col; - - if(k != row_of_biggest_in_col) - { - lu.row(k).swap(lu.row(row_of_biggest_in_col)); - ++nb_transpositions; - } - - if(k > > - */ - static bool blocked_lu(int rows, int cols, Scalar* lu_data, int luStride, int* row_transpositions, int& nb_transpositions, int maxBlockSize=256) - { - MapLU lu1(lu_data,StorageOrder==RowMajor?rows:luStride,StorageOrder==RowMajor?luStride:cols); - MatrixType lu(lu1,0,0,rows,cols); - - const int size = std::min(rows,cols); - - // if the matrix is too small, no blocking: - if(size<=16) - { - return unblocked_lu(lu, row_transpositions, nb_transpositions); - } - - // automatically adjust the number of subdivisions to the size - // of the matrix so that there is enough sub blocks: - int blockSize; - { - blockSize = size/8; - blockSize = (blockSize/16)*16; - blockSize = std::min(std::max(blockSize,8), maxBlockSize); - } - - nb_transpositions = 0; - for(int k = 0; k < size; k+=blockSize) - { - int bs = std::min(size-k,blockSize); // actual size of the block - int trows = rows - k - bs; // trailing rows - int tsize = size - k - bs; // trailing size - - // partition the matrix: - // A00 | A01 | A02 - // lu = A10 | A11 | A12 - // A20 | A21 | A22 - BlockType A_0(lu,0,0,rows,k); - BlockType A_2(lu,0,k+bs,rows,tsize); - BlockType A11(lu,k,k,bs,bs); - BlockType A12(lu,k,k+bs,bs,tsize); - BlockType A21(lu,k+bs,k,trows,bs); - BlockType A22(lu,k+bs,k+bs,trows,tsize); - - int nb_transpositions_in_panel; - // recursively calls the blocked LU algorithm with a very small - // blocking size: - if(!blocked_lu(trows+bs, bs, &lu.coeffRef(k,k), luStride, - row_transpositions+k, nb_transpositions_in_panel, 16)) - { - // end quickly with undefined coefficients, just avoid generating inf/nan values. - // before exiting, make sure to initialize the still uninitialized row_transpositions - // in a sane state without destroying what we already have. - for(int i=k; i().solveInPlace(A12); - - A22 -= A21 * A12; - } - } - return true; - } -}; - -/** \internal performs the LU decomposition with partial pivoting in-place. - */ -template -void ei_partial_lu_inplace(MatrixType& lu, IntVector& row_transpositions, int& nb_transpositions) -{ - ei_assert(lu.cols() == row_transpositions.size()); - ei_assert((&row_transpositions.coeffRef(1)-&row_transpositions.coeffRef(0)) == 1); - - ei_partial_lu_impl - - ::blocked_lu(lu.rows(), lu.cols(), &lu.coeffRef(0,0), lu.stride(), &row_transpositions.coeffRef(0), nb_transpositions); -} - -template -PartialLU& PartialLU::compute(const MatrixType& matrix) -{ - m_lu = matrix; - m_p.resize(matrix.rows()); - - ei_assert(matrix.rows() == matrix.cols() && "PartialLU is only for square (and moreover invertible) matrices"); - const int size = matrix.rows(); - - IntColVectorType rows_transpositions(size); - - int nb_transpositions; - ei_partial_lu_inplace(m_lu, rows_transpositions, nb_transpositions); - m_det_p = (nb_transpositions%2) ? -1 : 1; - - for(int k = 0; k < size; ++k) m_p.coeffRef(k) = k; - for(int k = size-1; k >= 0; --k) - std::swap(m_p.coeffRef(k), m_p.coeffRef(rows_transpositions.coeff(k))); - - m_isInitialized = true; - return *this; -} - -template -typename ei_traits::Scalar PartialLU::determinant() const -{ - ei_assert(m_isInitialized && "PartialLU is not initialized."); - return Scalar(m_det_p) * m_lu.diagonal().prod(); -} - -/***** Implementation of solve() *****************************************************/ - -template -struct ei_traits > -{ - typedef Matrix ReturnMatrixType; -}; - -template -struct ei_partiallu_solve_impl : public ReturnByValue > -{ - typedef typename ei_cleantype::type RhsNested; - typedef PartialLU LUType; - const LUType& m_lu; - const typename Rhs::Nested m_rhs; - - ei_partiallu_solve_impl(const LUType& lu, const Rhs& rhs) - : m_lu(lu), m_rhs(rhs) - {} - - inline int rows() const { return m_lu.matrixLU().cols(); } - inline int cols() const { return m_rhs.cols(); } - - template void evalTo(Dest& dst) const - { - /* The decomposition PA = LU can be rewritten as A = P^{-1} L U. - * So we proceed as follows: - * Step 1: compute c = Pb. - * Step 2: replace c by the solution x to Lx = c. - * Step 3: replace c by the solution x to Ux = c. - */ - - const int size = m_lu.matrixLU().rows(); - ei_assert(m_rhs.rows() == size); - - dst.resize(size, m_rhs.cols()); - - // Step 1 - for(int i = 0; i < size; ++i) dst.row(m_lu.permutationP().coeff(i)) = m_rhs.row(i); - - // Step 2 - m_lu.matrixLU().template triangularView().solveInPlace(dst); - - // Step 3 - m_lu.matrixLU().template triangularView().solveInPlace(dst); - } -}; - -/******** MatrixBase methods *******/ - -/** \lu_module - * - * \return the LU decomposition of \c *this. - * - * \sa class LU - */ -template -inline const PartialLU::PlainMatrixType> -MatrixBase::partialLu() const -{ - return PartialLU(eval()); -} - -#endif // EIGEN_PARTIALLU_H diff --git a/Eigen/src/LU/PartialPivLU.h b/Eigen/src/LU/PartialPivLU.h new file mode 100644 index 000000000..647ada38f --- /dev/null +++ b/Eigen/src/LU/PartialPivLU.h @@ -0,0 +1,493 @@ +// This file is part of Eigen, a lightweight C++ template library +// for linear algebra. +// +// Copyright (C) 2006-2009 Benoit Jacob +// Copyright (C) 2009 Gael Guennebaud +// +// Eigen is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 3 of the License, or (at your option) any later version. +// +// Alternatively, you can redistribute it and/or +// modify it under the terms of the GNU General Public License as +// published by the Free Software Foundation; either version 2 of +// the License, or (at your option) any later version. +// +// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License and a copy of the GNU General Public License along with +// Eigen. If not, see . + +#ifndef EIGEN_PARTIALLU_H +#define EIGEN_PARTIALLU_H + +template struct ei_partiallu_solve_impl; + +/** \ingroup LU_Module + * + * \class PartialPivLU + * + * \brief LU decomposition of a matrix with partial pivoting, and related features + * + * \param MatrixType the type of the matrix of which we are computing the LU decomposition + * + * This class represents a LU decomposition of a \b square \b invertible matrix, with partial pivoting: the matrix A + * is decomposed as A = PLU where L is unit-lower-triangular, U is upper-triangular, and P + * is a permutation matrix. + * + * Typically, partial pivoting LU decomposition is only considered numerically stable for square invertible + * matrices. Thus LAPACK's dgesv and dgesvx require the matrix to be square and invertible. The present class + * does the same. It will assert that the matrix is square, but it won't (actually it can't) check that the + * matrix is invertible: it is your task to check that you only use this decomposition on invertible matrices. + * + * The guaranteed safe alternative, working for all matrices, is the full pivoting LU decomposition, provided + * by class FullPivLU. + * + * This is \b not a rank-revealing LU decomposition. Many features are intentionally absent from this class, + * such as rank computation. If you need these features, use class FullPivLU. + * + * This LU decomposition is suitable to invert invertible matrices. It is what MatrixBase::inverse() uses + * in the general case. + * On the other hand, it is \b not suitable to determine whether a given matrix is invertible. + * + * The data of the LU decomposition can be directly accessed through the methods matrixLU(), permutationP(). + * + * \sa MatrixBase::partialPivLu(), MatrixBase::determinant(), MatrixBase::inverse(), MatrixBase::computeInverse(), class FullPivLU + */ +template class PartialPivLU +{ + public: + + typedef typename MatrixType::Scalar Scalar; + typedef typename NumTraits::Real RealScalar; + typedef Matrix IntRowVectorType; + typedef Matrix IntColVectorType; + typedef Matrix RowVectorType; + typedef Matrix ColVectorType; + + enum { MaxSmallDimAtCompileTime = EIGEN_ENUM_MIN( + MatrixType::MaxColsAtCompileTime, + MatrixType::MaxRowsAtCompileTime) + }; + + /** + * \brief Default Constructor. + * + * The default constructor is useful in cases in which the user intends to + * perform decompositions via PartialPivLU::compute(const MatrixType&). + */ + PartialPivLU(); + + /** Constructor. + * + * \param matrix the matrix of which to compute the LU decomposition. + * + * \warning The matrix should have full rank (e.g. if it's square, it should be invertible). + * If you need to deal with non-full rank, use class FullPivLU instead. + */ + PartialPivLU(const MatrixType& matrix); + + PartialPivLU& compute(const MatrixType& matrix); + + /** \returns the LU decomposition matrix: the upper-triangular part is U, the + * unit-lower-triangular part is L (at least for square matrices; in the non-square + * case, special care is needed, see the documentation of class FullPivLU). + * + * \sa matrixL(), matrixU() + */ + inline const MatrixType& matrixLU() const + { + ei_assert(m_isInitialized && "PartialPivLU is not initialized."); + return m_lu; + } + + /** \returns a vector of integers, whose size is the number of rows of the matrix being decomposed, + * representing the P permutation i.e. the permutation of the rows. For its precise meaning, + * see the examples given in the documentation of class FullPivLU. + */ + inline const IntColVectorType& permutationP() const + { + ei_assert(m_isInitialized && "PartialPivLU is not initialized."); + return m_p; + } + + /** This method returns a solution x to the equation Ax=b, where A is the matrix of which + * *this is the LU decomposition. + * + * \param b the right-hand-side of the equation to solve. Can be a vector or a matrix, + * the only requirement in order for the equation to make sense is that + * b.rows()==A.rows(), where A is the matrix of which *this is the LU decomposition. + * + * \returns the solution. + * + * Example: \include PartialPivLU_solve.cpp + * Output: \verbinclude PartialPivLU_solve.out + * + * Since this PartialPivLU class assumes anyway that the matrix A is invertible, the solution + * theoretically exists and is unique regardless of b. + * + * \note_about_checking_solutions + * + * \sa TriangularView::solve(), inverse(), computeInverse() + */ + template + inline const ei_partiallu_solve_impl + solve(const MatrixBase& b) const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return ei_partiallu_solve_impl(*this, b.derived()); + } + + /** \returns the inverse of the matrix of which *this is the LU decomposition. + * + * \warning The matrix being decomposed here is assumed to be invertible. If you need to check for + * invertibility, use class FullPivLU instead. + * + * \sa MatrixBase::inverse(), LU::inverse() + */ + inline const ei_partiallu_solve_impl > inverse() const + { + ei_assert(m_isInitialized && "LU is not initialized."); + return ei_partiallu_solve_impl > + (*this, MatrixType::Identity(m_lu.rows(), m_lu.cols()).nestByValue()); + } + + /** \returns the determinant of the matrix of which + * *this is the LU decomposition. It has only linear complexity + * (that is, O(n) where n is the dimension of the square matrix) + * as the LU decomposition has already been computed. + * + * \note For fixed-size matrices of size up to 4, MatrixBase::determinant() offers + * optimized paths. + * + * \warning a determinant can be very big or small, so for matrices + * of large enough dimension, there is a risk of overflow/underflow. + * + * \sa MatrixBase::determinant() + */ + typename ei_traits::Scalar determinant() const; + + protected: + MatrixType m_lu; + IntColVectorType m_p; + int m_det_p; + bool m_isInitialized; +}; + +template +PartialPivLU::PartialPivLU() + : m_lu(), + m_p(), + m_det_p(0), + m_isInitialized(false) +{ +} + +template +PartialPivLU::PartialPivLU(const MatrixType& matrix) + : m_lu(), + m_p(), + m_det_p(0), + m_isInitialized(false) +{ + compute(matrix); +} + + + +/** This is the blocked version of ei_lu_unblocked() */ +template +struct ei_partial_lu_impl +{ + // FIXME add a stride to Map, so that the following mapping becomes easier, + // another option would be to create an expression being able to automatically + // warp any Map, Matrix, and Block expressions as a unique type, but since that's exactly + // a Map + stride, why not adding a stride to Map, and convenient ctors from a Matrix, + // and Block. + typedef Map > MapLU; + typedef Block MatrixType; + typedef Block BlockType; + typedef typename MatrixType::RealScalar RealScalar; + + /** \internal performs the LU decomposition in-place of the matrix \a lu + * using an unblocked algorithm. + * + * In addition, this function returns the row transpositions in the + * vector \a row_transpositions which must have a size equal to the number + * of columns of the matrix \a lu, and an integer \a nb_transpositions + * which returns the actual number of transpositions. + * + * \returns false if some pivot is exactly zero, in which case the matrix is left with + * undefined coefficients (to avoid generating inf/nan values). Returns true + * otherwise. + */ + static bool unblocked_lu(MatrixType& lu, int* row_transpositions, int& nb_transpositions) + { + const int rows = lu.rows(); + const int size = std::min(lu.rows(),lu.cols()); + nb_transpositions = 0; + for(int k = 0; k < size; ++k) + { + int row_of_biggest_in_col; + RealScalar biggest_in_corner + = lu.col(k).end(rows-k).cwise().abs().maxCoeff(&row_of_biggest_in_col); + row_of_biggest_in_col += k; + + if(biggest_in_corner == 0) // the pivot is exactly zero: the matrix is singular + { + // end quickly, avoid generating inf/nan values. Although in this unblocked_lu case + // the result is still valid, there's no need to boast about it because + // the blocked_lu code can't guarantee the same. + // before exiting, make sure to initialize the still uninitialized row_transpositions + // in a sane state without destroying what we already have. + for(int i = k; i < size; i++) + row_transpositions[i] = i; + return false; + } + + row_transpositions[k] = row_of_biggest_in_col; + + if(k != row_of_biggest_in_col) + { + lu.row(k).swap(lu.row(row_of_biggest_in_col)); + ++nb_transpositions; + } + + if(k > > + */ + static bool blocked_lu(int rows, int cols, Scalar* lu_data, int luStride, int* row_transpositions, int& nb_transpositions, int maxBlockSize=256) + { + MapLU lu1(lu_data,StorageOrder==RowMajor?rows:luStride,StorageOrder==RowMajor?luStride:cols); + MatrixType lu(lu1,0,0,rows,cols); + + const int size = std::min(rows,cols); + + // if the matrix is too small, no blocking: + if(size<=16) + { + return unblocked_lu(lu, row_transpositions, nb_transpositions); + } + + // automatically adjust the number of subdivisions to the size + // of the matrix so that there is enough sub blocks: + int blockSize; + { + blockSize = size/8; + blockSize = (blockSize/16)*16; + blockSize = std::min(std::max(blockSize,8), maxBlockSize); + } + + nb_transpositions = 0; + for(int k = 0; k < size; k+=blockSize) + { + int bs = std::min(size-k,blockSize); // actual size of the block + int trows = rows - k - bs; // trailing rows + int tsize = size - k - bs; // trailing size + + // partition the matrix: + // A00 | A01 | A02 + // lu = A10 | A11 | A12 + // A20 | A21 | A22 + BlockType A_0(lu,0,0,rows,k); + BlockType A_2(lu,0,k+bs,rows,tsize); + BlockType A11(lu,k,k,bs,bs); + BlockType A12(lu,k,k+bs,bs,tsize); + BlockType A21(lu,k+bs,k,trows,bs); + BlockType A22(lu,k+bs,k+bs,trows,tsize); + + int nb_transpositions_in_panel; + // recursively calls the blocked LU algorithm with a very small + // blocking size: + if(!blocked_lu(trows+bs, bs, &lu.coeffRef(k,k), luStride, + row_transpositions+k, nb_transpositions_in_panel, 16)) + { + // end quickly with undefined coefficients, just avoid generating inf/nan values. + // before exiting, make sure to initialize the still uninitialized row_transpositions + // in a sane state without destroying what we already have. + for(int i=k; i().solveInPlace(A12); + + A22 -= A21 * A12; + } + } + return true; + } +}; + +/** \internal performs the LU decomposition with partial pivoting in-place. + */ +template +void ei_partial_lu_inplace(MatrixType& lu, IntVector& row_transpositions, int& nb_transpositions) +{ + ei_assert(lu.cols() == row_transpositions.size()); + ei_assert((&row_transpositions.coeffRef(1)-&row_transpositions.coeffRef(0)) == 1); + + ei_partial_lu_impl + + ::blocked_lu(lu.rows(), lu.cols(), &lu.coeffRef(0,0), lu.stride(), &row_transpositions.coeffRef(0), nb_transpositions); +} + +template +PartialPivLU& PartialPivLU::compute(const MatrixType& matrix) +{ + m_lu = matrix; + m_p.resize(matrix.rows()); + + ei_assert(matrix.rows() == matrix.cols() && "PartialPivLU is only for square (and moreover invertible) matrices"); + const int size = matrix.rows(); + + IntColVectorType rows_transpositions(size); + + int nb_transpositions; + ei_partial_lu_inplace(m_lu, rows_transpositions, nb_transpositions); + m_det_p = (nb_transpositions%2) ? -1 : 1; + + for(int k = 0; k < size; ++k) m_p.coeffRef(k) = k; + for(int k = size-1; k >= 0; --k) + std::swap(m_p.coeffRef(k), m_p.coeffRef(rows_transpositions.coeff(k))); + + m_isInitialized = true; + return *this; +} + +template +typename ei_traits::Scalar PartialPivLU::determinant() const +{ + ei_assert(m_isInitialized && "PartialPivLU is not initialized."); + return Scalar(m_det_p) * m_lu.diagonal().prod(); +} + +/***** Implementation of solve() *****************************************************/ + +template +struct ei_traits > +{ + typedef Matrix ReturnMatrixType; +}; + +template +struct ei_partiallu_solve_impl : public ReturnByValue > +{ + typedef typename ei_cleantype::type RhsNested; + typedef PartialPivLU LUType; + const LUType& m_lu; + const typename Rhs::Nested m_rhs; + + ei_partiallu_solve_impl(const LUType& lu, const Rhs& rhs) + : m_lu(lu), m_rhs(rhs) + {} + + inline int rows() const { return m_lu.matrixLU().cols(); } + inline int cols() const { return m_rhs.cols(); } + + template void evalTo(Dest& dst) const + { + /* The decomposition PA = LU can be rewritten as A = P^{-1} L U. + * So we proceed as follows: + * Step 1: compute c = Pb. + * Step 2: replace c by the solution x to Lx = c. + * Step 3: replace c by the solution x to Ux = c. + */ + + const int size = m_lu.matrixLU().rows(); + ei_assert(m_rhs.rows() == size); + + dst.resize(size, m_rhs.cols()); + + // Step 1 + for(int i = 0; i < size; ++i) dst.row(m_lu.permutationP().coeff(i)) = m_rhs.row(i); + + // Step 2 + m_lu.matrixLU().template triangularView().solveInPlace(dst); + + // Step 3 + m_lu.matrixLU().template triangularView().solveInPlace(dst); + } +}; + +/******** MatrixBase methods *******/ + +/** \lu_module + * + * \return the partial-pivoting LU decomposition of \c *this. + * + * \sa class PartialPivLU + */ +template +inline const PartialPivLU::PlainMatrixType> +MatrixBase::partialPivLu() const +{ + return PartialPivLU(eval()); +} + +/** \lu_module + * + * Synonym of partialPivLu(). + * + * \return the partial-pivoting LU decomposition of \c *this. + * + * \sa class PartialPivLU + */ +template +inline const PartialPivLU::PlainMatrixType> +MatrixBase::lu() const +{ + return PartialPivLU(eval()); +} + +#endif // EIGEN_PARTIALLU_H -- cgit v1.2.3