Extend documentation and add examples for ComplexEigenSolver.

4 files changed, 69 insertions, 6 deletions

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<typename _MatrixType> class ComplexEigenSolver
@@ -86,10 +98,10 @@ template<typename _MatrixType> 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<typename _MatrixType> 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<typename _MatrixType> 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<typename _MatrixType> 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<MatrixXcf> 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<float> 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<MatrixXcf> 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<MatrixXcf> ces(ones);
+cout << "The first eigenvector of the 3x3 matrix of ones is:" 
+     << endl << ces.eigenvectors().col(1) << endl;