From a8f5ef93880e422db26c202ef514b7a796498e9f Mon Sep 17 00:00:00 2001 From: Jitse Niesen Date: Sun, 27 Feb 2011 14:06:55 +0000 Subject: [PATCH] Document (non)sorting of eigenvalues. Also, update docs for (Generalized)SelfAdjointEigenSolver to reflect that these two classes were split apart. --- Eigen/src/Eigenvalues/ComplexEigenSolver.h | 3 ++- Eigen/src/Eigenvalues/EigenSolver.h | 4 ++- .../GeneralizedSelfAdjointEigenSolver.h | 13 +++------- .../src/Eigenvalues/SelfAdjointEigenSolver.h | 26 +++++++++---------- Eigen/src/SVD/JacobiSVD.h | 2 +- 5 files changed, 22 insertions(+), 26 deletions(-) diff --git a/Eigen/src/Eigenvalues/ComplexEigenSolver.h b/Eigen/src/Eigenvalues/ComplexEigenSolver.h index 638e21e94..57e00227d 100644 --- a/Eigen/src/Eigenvalues/ComplexEigenSolver.h +++ b/Eigen/src/Eigenvalues/ComplexEigenSolver.h @@ -186,7 +186,8 @@ template class ComplexEigenSolver * This function returns a column vector containing the * eigenvalues. Eigenvalues are repeated according to their * algebraic multiplicity, so there are as many eigenvalues as - * rows in the matrix. + * rows in the matrix. The eigenvalues are not sorted in any particular + * order. * * Example: \include ComplexEigenSolver_eigenvalues.cpp * Output: \verbinclude ComplexEigenSolver_eigenvalues.out diff --git a/Eigen/src/Eigenvalues/EigenSolver.h b/Eigen/src/Eigenvalues/EigenSolver.h index 5a59ccbd4..b3594655a 100644 --- a/Eigen/src/Eigenvalues/EigenSolver.h +++ b/Eigen/src/Eigenvalues/EigenSolver.h @@ -228,6 +228,7 @@ template class EigenSolver * block-diagonal. The blocks on the diagonal are either 1-by-1 or 2-by-2 * blocks of the form * \f$ \begin{bmatrix} u & v \\ -v & u \end{bmatrix} \f$. + * These blocks are not sorted in any particular order. * The matrix \f$ D \f$ and the matrix \f$ V \f$ returned by * pseudoEigenvectors() satisfy \f$ AV = VD \f$. * @@ -244,7 +245,8 @@ template class EigenSolver * compute(const MatrixType&, bool) has been called before. * * The eigenvalues are repeated according to their algebraic multiplicity, - * so there are as many eigenvalues as rows in the matrix. + * so there are as many eigenvalues as rows in the matrix. The eigenvalues + * are not sorted in any particular order. * * Example: \include EigenSolver_eigenvalues.cpp * Output: \verbinclude EigenSolver_eigenvalues.out diff --git a/Eigen/src/Eigenvalues/GeneralizedSelfAdjointEigenSolver.h b/Eigen/src/Eigenvalues/GeneralizedSelfAdjointEigenSolver.h index a19e8cf24..a0ece70c4 100644 --- a/Eigen/src/Eigenvalues/GeneralizedSelfAdjointEigenSolver.h +++ b/Eigen/src/Eigenvalues/GeneralizedSelfAdjointEigenSolver.h @@ -70,13 +70,9 @@ class GeneralizedSelfAdjointEigenSolver : public SelfAdjointEigenSolver<_MatrixT /** \brief Default constructor for fixed-size matrices. * * The default constructor is useful in cases in which the user intends to - * perform decompositions via compute(const MatrixType&, bool) or - * compute(const MatrixType&, const MatrixType&, bool). This constructor + * perform decompositions via compute(). This constructor * can only be used if \p _MatrixType is a fixed-size matrix; use - * SelfAdjointEigenSolver(Index) for dynamic-size matrices. - * - * Example: \include SelfAdjointEigenSolver_SelfAdjointEigenSolver.cpp - * Output: \verbinclude SelfAdjointEigenSolver_SelfAdjointEigenSolver.out + * GeneralizedSelfAdjointEigenSolver(Index) for dynamic-size matrices. */ GeneralizedSelfAdjointEigenSolver() : Base() {} @@ -86,12 +82,11 @@ class GeneralizedSelfAdjointEigenSolver : public SelfAdjointEigenSolver<_MatrixT * eigenvalues and eigenvectors will be computed. * * This constructor is useful for dynamic-size matrices, when the user - * intends to perform decompositions via compute(const MatrixType&, bool) - * or compute(const MatrixType&, const MatrixType&, bool). The \p size + * intends to perform decompositions via compute(). The \p size * parameter is only used as a hint. It is not an error to give a wrong * \p size, but it may impair performance. * - * \sa compute(const MatrixType&, bool) for an example + * \sa compute() for an example */ GeneralizedSelfAdjointEigenSolver(Index size) : Base(size) diff --git a/Eigen/src/Eigenvalues/SelfAdjointEigenSolver.h b/Eigen/src/Eigenvalues/SelfAdjointEigenSolver.h index 5f239fd5b..f79492818 100644 --- a/Eigen/src/Eigenvalues/SelfAdjointEigenSolver.h +++ b/Eigen/src/Eigenvalues/SelfAdjointEigenSolver.h @@ -62,12 +62,12 @@ class GeneralizedSelfAdjointEigenSolver; * * Call the function compute() to compute the eigenvalues and eigenvectors of * a given matrix. Alternatively, you can use the - * SelfAdjointEigenSolver(const MatrixType&, bool) constructor which computes + * SelfAdjointEigenSolver(const MatrixType&, int) constructor which computes * the eigenvalues and eigenvectors at construction time. Once the eigenvalue * and eigenvectors are computed, they can be retrieved with the eigenvalues() * and eigenvectors() functions. * - * The documentation for SelfAdjointEigenSolver(const MatrixType&, bool) + * The documentation for SelfAdjointEigenSolver(const MatrixType&, int) * contains an example of the typical use of this class. * * To solve the \em generalized eigenvalue problem \f$ Av = \lambda Bv \f$ and @@ -110,8 +110,7 @@ template class SelfAdjointEigenSolver /** \brief Default constructor for fixed-size matrices. * * The default constructor is useful in cases in which the user intends to - * perform decompositions via compute(const MatrixType&, bool) or - * compute(const MatrixType&, const MatrixType&, bool). This constructor + * perform decompositions via compute(). This constructor * can only be used if \p _MatrixType is a fixed-size matrix; use * SelfAdjointEigenSolver(Index) for dynamic-size matrices. * @@ -131,12 +130,11 @@ template class SelfAdjointEigenSolver * eigenvalues and eigenvectors will be computed. * * This constructor is useful for dynamic-size matrices, when the user - * intends to perform decompositions via compute(const MatrixType&, bool) - * or compute(const MatrixType&, const MatrixType&, bool). The \p size + * intends to perform decompositions via compute(). The \p size * parameter is only used as a hint. It is not an error to give a wrong * \p size, but it may impair performance. * - * \sa compute(const MatrixType&, bool) for an example + * \sa compute() for an example */ SelfAdjointEigenSolver(Index size) : m_eivec(size, size), @@ -151,15 +149,14 @@ template class SelfAdjointEigenSolver * be computed. Only the lower triangular part of the matrix is referenced. * \param[in] options Can be ComputeEigenvectors (default) or EigenvaluesOnly. * - * This constructor calls compute(const MatrixType&, bool) to compute the + * This constructor calls compute(const MatrixType&, int) to compute the * eigenvalues of the matrix \p matrix. The eigenvectors are computed if * \p options equals ComputeEigenvectors. * * Example: \include SelfAdjointEigenSolver_SelfAdjointEigenSolver_MatrixType.cpp * Output: \verbinclude SelfAdjointEigenSolver_SelfAdjointEigenSolver_MatrixType.out * - * \sa compute(const MatrixType&, bool), - * SelfAdjointEigenSolver(const MatrixType&, const MatrixType&, bool) + * \sa compute(const MatrixType&, int) */ SelfAdjointEigenSolver(const MatrixType& matrix, int options = ComputeEigenvectors) : m_eivec(matrix.rows(), matrix.cols()), @@ -198,11 +195,11 @@ template class SelfAdjointEigenSolver * Example: \include SelfAdjointEigenSolver_compute_MatrixType.cpp * Output: \verbinclude SelfAdjointEigenSolver_compute_MatrixType.out * - * \sa SelfAdjointEigenSolver(const MatrixType&, bool) + * \sa SelfAdjointEigenSolver(const MatrixType&, int) */ SelfAdjointEigenSolver& compute(const MatrixType& matrix, int options = ComputeEigenvectors); - /** \brief Returns the eigenvectors of given matrix (pencil). + /** \brief Returns the eigenvectors of given matrix. * * \returns A const reference to the matrix whose columns are the eigenvectors. * @@ -227,14 +224,15 @@ template class SelfAdjointEigenSolver return m_eivec; } - /** \brief Returns the eigenvalues of given matrix (pencil). + /** \brief Returns the eigenvalues of given matrix. * * \returns A const reference to the column vector containing the eigenvalues. * * \pre The eigenvalues have been computed before. * * The eigenvalues are repeated according to their algebraic multiplicity, - * so there are as many eigenvalues as rows in the matrix. + * so there are as many eigenvalues as rows in the matrix. The eigenvalues + * are sorted in increasing order. * * Example: \include SelfAdjointEigenSolver_eigenvalues.cpp * Output: \verbinclude SelfAdjointEigenSolver_eigenvalues.out diff --git a/Eigen/src/SVD/JacobiSVD.h b/Eigen/src/SVD/JacobiSVD.h index 23b632a6b..270569214 100644 --- a/Eigen/src/SVD/JacobiSVD.h +++ b/Eigen/src/SVD/JacobiSVD.h @@ -452,7 +452,7 @@ template class JacobiSVD /** \returns the vector of singular values. * * For the SVD decomposition of a n-by-p matrix, letting \a m be the minimum of \a n and \a p, the - * returned vector has size \a m. + * returned vector has size \a m. Singular values are always sorted in decreasing order. */ const SingularValuesType& singularValues() const {