From d3e271c47e373146345f411900772d0d2627b0ea Mon Sep 17 00:00:00 2001 From: Jitse Niesen Date: Fri, 19 Mar 2010 18:23:36 +0000 Subject: [PATCH] Extend documentation and add examples for ComplexEigenSolver. --- Eigen/src/Eigenvalues/ComplexEigenSolver.h | 51 ++++++++++++++++--- doc/snippets/ComplexEigenSolver_compute.cpp | 16 ++++++ .../ComplexEigenSolver_eigenvalues.cpp | 4 ++ .../ComplexEigenSolver_eigenvectors.cpp | 4 ++ 4 files changed, 69 insertions(+), 6 deletions(-) create mode 100644 doc/snippets/ComplexEigenSolver_compute.cpp create mode 100644 doc/snippets/ComplexEigenSolver_eigenvalues.cpp create mode 100644 doc/snippets/ComplexEigenSolver_eigenvectors.cpp diff --git a/Eigen/src/Eigenvalues/ComplexEigenSolver.h b/Eigen/src/Eigenvalues/ComplexEigenSolver.h index 38284ba5f..86851eca4 100644 --- a/Eigen/src/Eigenvalues/ComplexEigenSolver.h +++ b/Eigen/src/Eigenvalues/ComplexEigenSolver.h @@ -37,6 +37,18 @@ * computing the eigendecomposition; this is expected to be an * instantiation of the Matrix class template. * + * The eigenvalues and eigenvectors of a matrix \f$ A \f$ are scalars + * \f$ \lambda \f$ and vectors \f$ v \f$ such that \f$ Av = \lambda v \f$. + * The eigendecomposition of a matrix is \f$ A = V D V^{-1} \f$, + * where \f$ D \f$ is a diagonal matrix. The entries on the diagonal + * of \f$ D \f$ are the eigenvalues and the columns of \f$ V \f$ are + * the eigenvectors. + * + * The main function in this class is compute(), which computes the + * eigenvalues and eigenvectors of a given function. The + * documentation for that function contains an example showing the + * main features of the class. + * * \sa class EigenSolver, class SelfAdjointEigenSolver */ template class ComplexEigenSolver @@ -86,10 +98,10 @@ template class ComplexEigenSolver {} /** \brief Constructor; computes eigendecomposition of given matrix. - * - * This constructor calls compute() to compute the eigendecomposition. * * \param[in] matrix %Matrix whose eigendecomposition is to be computed. + * + * This constructor calls compute() to compute the eigendecomposition. */ ComplexEigenSolver(const MatrixType& matrix) : m_eivec(matrix.rows(),matrix.cols()), @@ -99,14 +111,38 @@ template class ComplexEigenSolver compute(matrix); } - /** \brief Returns the eigenvectors of given matrix. */ + /** \brief Returns the eigenvectors of given matrix. + * + * It is assumed that either the constructor + * ComplexEigenSolver(const MatrixType& matrix) or the member + * function compute(const MatrixType& matrix) has been called + * before to compute the eigendecomposition of a matrix. This + * function returns the matrix \f$ V \f$ in the + * eigendecomposition \f$ A = V D V^{-1} \f$. The columns of \f$ + * V \f$ are the eigenvectors. The eigenvectors are normalized to + * have (Euclidean) norm equal to one, and are in the same order + * as the eigenvalues as returned by eigenvalues(). + * + * Example: \include ComplexEigenSolver_eigenvectors.cpp + * Output: \verbinclude ComplexEigenSolver_eigenvectors.out + */ EigenvectorType eigenvectors() const { ei_assert(m_isInitialized && "ComplexEigenSolver is not initialized."); return m_eivec; } - /** \brief Returns the eigenvalues of given matrix. */ + /** \brief Returns the eigenvalues of given matrix. + * + * It is assumed that either the constructor + * ComplexEigenSolver(const MatrixType& matrix) or the member + * function compute(const MatrixType& matrix) has been called + * before to compute the eigendecomposition of a matrix. This + * function returns a column vector containing the eigenvalues. + * + * Example: \include ComplexEigenSolver_eigenvalues.cpp + * Output: \verbinclude ComplexEigenSolver_eigenvalues.out + */ EigenvalueType eigenvalues() const { ei_assert(m_isInitialized && "ComplexEigenSolver is not initialized."); @@ -114,6 +150,8 @@ template class ComplexEigenSolver } /** \brief Computes eigendecomposition of given matrix. + * + * \param[in] matrix %Matrix whose eigendecomposition is to be computed. * * This function computes the eigenvalues and eigenvectors of \p * matrix. The eigenvalues() and eigenvectors() functions can be @@ -126,8 +164,9 @@ template class ComplexEigenSolver * The cost of the computation is dominated by the cost of the * Schur decomposition, which is \f$ O(n^3) \f$ where \f$ n \f$ * is the size of the matrix. - * - * \param[in] matrix %Matrix whose eigendecomposition is to be computed. + * + * Example: \include ComplexEigenSolver_compute.cpp + * Output: \verbinclude ComplexEigenSolver_compute.out */ void compute(const MatrixType& matrix); diff --git a/doc/snippets/ComplexEigenSolver_compute.cpp b/doc/snippets/ComplexEigenSolver_compute.cpp new file mode 100644 index 000000000..11d6bd399 --- /dev/null +++ b/doc/snippets/ComplexEigenSolver_compute.cpp @@ -0,0 +1,16 @@ +MatrixXcf A = MatrixXcf::Random(4,4); +cout << "Here is a random 4x4 matrix, A:" << endl << A << endl << endl; + +ComplexEigenSolver ces; +ces.compute(A); +cout << "The eigenvalues of A are:" << endl << ces.eigenvalues() << endl; +cout << "The matrix of eigenvectors, V, is:" << endl << ces.eigenvectors() << endl << endl; + +complex lambda = ces.eigenvalues()[0]; +cout << "Consider the first eigenvalue, lambda = " << lambda << endl; +VectorXcf v = ces.eigenvectors().col(0); +cout << "If v is the corresponding eigenvector, then lambda * v = " << endl << lambda * v << endl; +cout << "... and A * v = " << endl << A * v << endl << endl; + +cout << "Finally, V * D * V^(-1) = " << endl + << ces.eigenvectors() * ces.eigenvalues().asDiagonal() * ces.eigenvectors().inverse() << endl; diff --git a/doc/snippets/ComplexEigenSolver_eigenvalues.cpp b/doc/snippets/ComplexEigenSolver_eigenvalues.cpp new file mode 100644 index 000000000..1afa8b086 --- /dev/null +++ b/doc/snippets/ComplexEigenSolver_eigenvalues.cpp @@ -0,0 +1,4 @@ +MatrixXcf ones = MatrixXcf::Ones(3,3); +ComplexEigenSolver ces(ones); +cout << "The eigenvalues of the 3x3 matrix of ones are:" + << endl << ces.eigenvalues() << endl; diff --git a/doc/snippets/ComplexEigenSolver_eigenvectors.cpp b/doc/snippets/ComplexEigenSolver_eigenvectors.cpp new file mode 100644 index 000000000..bb1c2ccf1 --- /dev/null +++ b/doc/snippets/ComplexEigenSolver_eigenvectors.cpp @@ -0,0 +1,4 @@ +MatrixXcf ones = MatrixXcf::Ones(3,3); +ComplexEigenSolver ces(ones); +cout << "The first eigenvector of the 3x3 matrix of ones is:" + << endl << ces.eigenvectors().col(1) << endl;