eigen/doc/TopicLinearAlgebraDecompositions.dox

namespace Eigen {

/** \page TopicLinearAlgebraDecompositions Linear algebra and decompositions


\section TopicLinAlgBigTable Catalogue of decompositions offered by Eigen

<table border="1">

    <tr>
        <td></td>
        <td colspan="5" align="center">Generic information, not Eigen-specific</td>
        <td colspan="3" align="center">Eigen-specific</td>
    </tr>

    <tr>
        <td>Decomposition</td>
        <td>Requirements on the matrix</td>
        <td>Speed</td>
        <td>Algorithm reliability and accuracy</td>
        <td>Rank-revealing</td>
        <td>Allows to compute (besides linear solving)</td>
        <td>Linear solver provided by Eigen</td>
        <td>Maturity of Eigen's implementation</td>
        <td>Optimizations</td>
    </tr>

    <tr>
        <td>PartialPivLU</td>
        <td>Invertible</td>
        <td>Fast</td>
        <td>Depends on condition number</td>
        <td>-</td>
        <td>-</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td>Blocking</td>
    </tr>

    <tr>
        <td>FullPivLU</td>
        <td>-</td>
        <td>Slow</td>
        <td>Proven</td>
        <td>Yes</td>
        <td>-</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td>-</td>
    </tr>

    <tr>
        <td>HouseholderQR</td>
        <td>-</td>
        <td>Fast</td>
        <td>Depends on condition number</td>
        <td>-</td>
        <td>Orthogonalization</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td>Blocking</td>
    </tr>

    <tr>
        <td>ColPivHouseholderQR</td>
        <td>-</td>
        <td>Fast</td>
        <td>Good</td>
        <td>Yes</td>
        <td>Orthogonalization</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td><em>Soon: blocking</em></td>
    </tr>

    <tr>
        <td>FullPivHouseholderQR</td>
        <td>-</td>
        <td>Slow</td>
        <td>Proven</td>
        <td>Yes</td>
        <td>Orthogonalization</td>
        <td>Yes</td>
        <td>Average</td>
        <td>-</td>
    </tr>

    <tr>
        <td>LLT</td>
        <td>Positive definite</td>
        <td>Very fast</td>
        <td>Depends on condition number</td>
        <td>-</td>
        <td>-</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td>Blocking \n <em>Soon: meta unroller</em></td>
    </tr>

    <tr>
        <td>LDLT</td>
        <td>Positive or negative semidefinite<sup><a href="#note1">1</a></sup></td>
        <td>Very fast</td>
        <td>Good</td>
        <td>-</td>
        <td>-</td>
        <td>Yes</td>
        <td>Excellent</td>
        <td><em>Soon: blocking</em></td>
    </tr>

    <tr><td colspan="8">\n Singular values and eigenvalues decompositions</td></tr>

    <tr>
        <td>SVD</td>
        <td>-</td>
        <td>Average</td>
        <td>Good</td>
        <td>Yes</td>
        <td>Singular values/vectors, least squares</td>
        <td>Yes</td>
        <td>Average</td>
        <td>-</td>
    </tr>

    <tr>
        <td>JacobiSVD</td>
        <td>-</td>
        <td>Slow (but fast for small matrices)</td>
        <td>Proven</td>
        <td>Yes</td>
        <td>Singular values/vectors, least squares</td>
        <td>-</td>
        <td>Excellent</td>
        <td>-</td>
    </tr>

    <tr>
        <td>SelfAdjointEigenSolver</td>
        <td>Self-adjoint</td>
        <td>Fast-average<sup><a href="#note2">2</a></sup></td>
        <td>Good</td>
        <td>Yes</td>
        <td>Eigenvalues/vectors</td>
        <td>-</td>
        <td>Good</td>
        <td><em>Soon: specializations for 2x2 and 3x3</em></td>
    </tr>

    <tr>
        <td>ComplexEigenSolver</td>
        <td>Square</td>
        <td>Slow-very slow<sup><a href="#note2">2</a></sup></td>
        <td>Depends on condition number</td>
        <td>Yes</td>
        <td>Eigenvalues/vectors</td>
        <td>-</td>
        <td>Average</td>
        <td>-</td>
    </tr>

    <tr>
        <td>EigenSolver</td>
        <td>Square and real</td>
        <td>Average-slow<sup><a href="#note2">2</a></sup></td>
        <td>Depends on condition number</td>
        <td>Yes</td>
        <td>Eigenvalues/vectors</td>
        <td>-</td>
        <td>TODO Jitse answer this</td>
        <td>-</td>
    </tr>

    <tr>
        <td>GeneralizedSelfAdjointEigenSolver</td>
        <td>Square</td>
        <td>Fast-average<sup><a href="#note2">2</a></sup></td>
        <td>Depends on condition number</td>
        <td>-</td>
        <td>Generalized eigenvalues/vectors</td>
        <td>-</td>
        <td>Good</td>
        <td>-</td>
    </tr>

    <tr><td colspan="8">\n Helper decompositions</td></tr>

    <tr>
        <td>RealSchur</td>
        <td>Square and real</td>
        <td>Average-slow<sup><a href="#note2">2</a></sup></td>
        <td>Depends on condition number</td>
        <td>Yes</td>
        <td>-</td>
        <td>-</td>
        <td>TODO Jitse answer this</td>
        <td>-</td>
    </tr>

    <tr>
        <td>ComplexSchur</td>
        <td>Square and real</td>
        <td>Slow-very slow<sup><a href="#note2">2</a></sup></td>
        <td>Depends on condition number</td>
        <td>Yes</td>
        <td>-</td>
        <td>-</td>
        <td>Average</td>
        <td>-</td>
    </tr>

    <tr>
        <td>UpperBidiagonalization</td>
        <td>rows >= columns</td>
        <td>Fast</td>
        <td>Good</td>
        <td>-</td>
        <td>-</td>
        <td>-</td>
        <td>Good</td>
        <td>-</td>
    </tr>

    <tr>
        <td>Tridiagonalization</td>
        <td>Self-adjoint</td>
        <td>Fast</td>
        <td>Good</td>
        <td>-</td>
        <td>-</td>
        <td>-</td>
        <td>Good</td>
        <td><em>Soon: blocking</em></td>
    </tr>

    <tr>
        <td>HessenbergDecomposition</td>
        <td>Square</td>
        <td>Average</td>
        <td>Good</td>
        <td>-</td>
        <td>-</td>
        <td>-</td>
        <td>Good</td>
        <td><em>Soon: blocking</em></td>
    </tr>

</table>

\b Notes:
<ul>
<li><a name="note1">\b 1: </a>There exist a couple of variants of the LDLT algorithm. Eigen's one produces a pure diagonal matrix, and therefore it cannot handle indefinite matrix, unlike Lapack's one which produces a block diagonal matrix.</li>
<li><a name="note2">\b 2: </a>Eigenvalues and Schur decompositions rely on iterative algorithms. Their convergence speed depends on how the eigenvalues are well separated.</li>
</ul>

\section TopicLinAlgTerminology Terminology

<dl>
  <dt><b>Selfadjoint</b></dt>
    <dd>For a real matrix, selfadjoint is a synonym for symmetric. For a complex matrix, selfadjoint is a synonym for \em hermitian.
        More generally, a matrix \f$ A \f$ is selfadjoint if and only if it is equal to its adjoint \f$ A^* \f$. The adjoint is also called the \em conjugate \em transpose. </dd>
  <dt><b>Positive/negative definite</b></dt>
    <dd>A selfadjoint matrix \f$ A \f$ is positive definite if \f$ v^* A v > 0 \f$ for any non zero vector \f$ v \f$.
        In the same vein, it is negative definite if \f$ v^* A v < 0 \f$ for any non zero vector \f$ v \f$ </dd>
  <dt><b>Positive/negative semidefinite</b></dt>
    <dd>A selfadjoint matrix \f$ A \f$ is positive semi-definite if \f$ v^* A v \ge 0 \f$ for any non zero vector \f$ v \f$.
        In the same vein, it is negative semi-definite if \f$ v^* A v \le 0 \f$ for any non zero vector \f$ v \f$ </dd>

  <dt><b>Blocking</b></dt>
    <dd>Means the algorithm can work per block, whence guarantying a good scaling of the performance for large matrices.</dd>
  <dt><b>Meta-unroller</b></dt>
    <dd>Means the algorithm is automatically and explicitly unrolled for very small fixed size matrices.</dd>
  <dt><b></b></dt>
    <dd></dd>
</dl>

*/

}