Big API change in Cholesky module:

 * rename Cholesky to LLT
 * rename CholeskyWithoutSquareRoot to LDLT
 * rename MatrixBase::cholesky() to llt()
 * rename MatrixBase::choleskyNoSqrt() to ldlt()
 * make {LLT,LDLT}::solve() API consistent with other modules

Note that we are going to keep a source compatibility untill the next beta release.
E.g., the "old" Cholesky* classes, etc are still available for some time.
To be clear, Eigen beta2 should be (hopefully) source compatible with beta1,
and so beta2 will contain all the deprecated API of beta1. Those features marked
as deprecated will be removed in beta3 (or in the final 2.0 if there is no beta 3 !).

Also includes various updated in sparse Cholesky.

1 files changed, 26 insertions, 30 deletions

diff --git a/Eigen/src/Cholesky/Cholesky.h b/Eigen/src/Cholesky/Cholesky.h
index b94fea8dc..ada413b33 100644
--- a/Eigen/src/Cholesky/Cholesky.h
+++ b/Eigen/src/Cholesky/Cholesky.h
@@ -29,22 +29,7 @@
   *
   * \class Cholesky
   *
-  * \brief Standard Cholesky decomposition of a matrix and associated features
-  *
-  * \param MatrixType the type of the matrix of which we are computing the Cholesky decomposition
-  *
-  * This class performs a standard Cholesky decomposition of a symmetric, positive definite
-  * matrix A such that A = LL^* = U^*U, where L is lower triangular.
-  *
-  * While the Cholesky decomposition is particularly useful to solve selfadjoint problems like  D^*D x = b,
-  * for that purpose, we recommend the Cholesky decomposition without square root which is more stable
-  * and even faster. Nevertheless, this standard Cholesky decomposition remains useful in many other
-  * situations like generalised eigen problems with hermitian matrices.
-  *
-  * Note that during the decomposition, only the upper triangular part of A is considered. Therefore,
-  * the strict lower part does not have to store correct values.
-  *
-  * \sa MatrixBase::cholesky(), class CholeskyWithoutSquareRoot
+  * \deprecated this class has been renamed LLT
   */
 template<typename MatrixType> class Cholesky
 {
@@ -72,7 +57,10 @@ template<typename MatrixType> class Cholesky
     inline bool isPositiveDefinite(void) const { return m_isPositiveDefinite; }
 
     template<typename Derived>
-    typename Derived::Eval solve(const MatrixBase<Derived> &b) const;
+    typename Derived::Eval solve(const MatrixBase<Derived> &b) const EIGEN_DEPRECATED;
+
+    template<typename RhsDerived, typename ResDerived>
+    bool solve(const MatrixBase<RhsDerived> &b, MatrixBase<ResDerived> *result) const;
 
     template<typename Derived>
     bool solveInPlace(MatrixBase<Derived> &bAndX) const;
@@ -128,16 +116,7 @@ void Cholesky<MatrixType>::compute(const MatrixType& a)
   }
 }
 
-/** \returns the solution of \f$ A x = b \f$ using the current decomposition of A.
-  * In other words, it returns \f$ A^{-1} b \f$ computing
-  * \f$ {L^{*}}^{-1} L^{-1} b \f$ from right to left.
-  * \param b the column vector \f$ b \f$, which can also be a matrix.
-  *
-  * Example: \include Cholesky_solve.cpp
-  * Output: \verbinclude Cholesky_solve.out
-  *
-  * \sa MatrixBase::cholesky(), CholeskyWithoutSquareRoot::solve()
-  */
+/** \deprecated */
 template<typename MatrixType>
 template<typename Derived>
 typename Derived::Eval Cholesky<MatrixType>::solve(const MatrixBase<Derived> &b) const
@@ -147,7 +126,6 @@ typename Derived::Eval Cholesky<MatrixType>::solve(const MatrixBase<Derived> &b)
   typename ei_eval_to_column_major<Derived>::type x(b);
   solveInPlace(x);
   return x;
-  //return m_matrix.adjoint().template part<Upper>().solveTriangular(matrixL().solveTriangular(b));
 }
 
 /** Computes the solution x of \f$ A x = b \f$ using the current decomposition of A.
@@ -162,7 +140,25 @@ typename Derived::Eval Cholesky<MatrixType>::solve(const MatrixBase<Derived> &b)
   * Example: \include Cholesky_solve.cpp
   * Output: \verbinclude Cholesky_solve.out
   *
-  * \sa MatrixBase::cholesky(), Cholesky::solve()
+  * \sa MatrixBase::cholesky(), Cholesky::solveInPlace()
+  */
+template<typename MatrixType>
+template<typename RhsDerived, typename ResDerived>
+bool Cholesky<MatrixType>::solve(const MatrixBase<RhsDerived> &b, MatrixBase<ResDerived> *result) const
+{
+  const int size = m_matrix.rows();
+  ei_assert(size==b.rows() && "Cholesky::solve(): invalid number of rows of the right hand side matrix b");
+  return solveInPlace((*result) = b);
+}
+
+/** This is the \em in-place version of solve().
+  *
+  * \param bAndX represents both the right-hand side matrix b and result x.
+  *
+  * This version avoids a copy when the right hand side matrix b is not
+  * needed anymore.
+  *
+  * \sa Cholesky::solve(), MatrixBase::cholesky()
   */
 template<typename MatrixType>
 template<typename Derived>
@@ -178,7 +174,7 @@ bool Cholesky<MatrixType>::solveInPlace(MatrixBase<Derived> &bAndX) const
 }
 
 /** \cholesky_module
-  * \returns the Cholesky decomposition of \c *this
+  * \deprecated has been renamed llt()
   */
 template<typename Derived>
 inline const Cholesky<typename MatrixBase<Derived>::EvalType>