improve documentation of some sparse related classes

9 files changed, 62 insertions, 52 deletions

diff --git a/Eigen/src/CholmodSupport/CholmodSupport.h b/Eigen/src/CholmodSupport/CholmodSupport.h
index c7cf3ad63..2d5530682 100644
--- a/Eigen/src/CholmodSupport/CholmodSupport.h
+++ b/Eigen/src/CholmodSupport/CholmodSupport.h
@@ -161,7 +161,7 @@ enum CholmodMode {
   * \tparam _UpLo the triangular part that will be used for the computations. It can be Lower
   *               or Upper. Default is Lower.
   *
-  * \sa TutorialSparseDirectSolvers
+  * \sa \ref TutorialSparseDirectSolvers
   */
 template<typename _MatrixType, int _UpLo = Lower>
 class CholmodDecomposition
diff --git a/Eigen/src/IterativeLinearSolvers/BasicPreconditioners.h b/Eigen/src/IterativeLinearSolvers/BasicPreconditioners.h
index d9edd1461..b1da2f8ce 100644
--- a/Eigen/src/IterativeLinearSolvers/BasicPreconditioners.h
+++ b/Eigen/src/IterativeLinearSolvers/BasicPreconditioners.h
@@ -25,7 +25,8 @@
 #ifndef EIGEN_BASIC_PRECONDITIONERS_H
 #define EIGEN_BASIC_PRECONDITIONERS_H
 
-/** \brief A preconditioner based on the digonal entries
+/** \ingroup IterativeLinearSolvers_Module
+  * \brief A preconditioner based on the digonal entries
   *
   * This class allows to approximately solve for A.x = b problems assuming A is a diagonal matrix.
   * In other words, this preconditioner neglects all off diagonal entries and, in Eigen's language, solves for:
@@ -116,7 +117,8 @@ struct solve_retval<DiagonalPreconditioner<_MatrixType>, Rhs>
 
 }
 
-/** \brief A naive preconditioner which approximates any matrix as the identity matrix
+/** \ingroup IterativeLinearSolvers_Module
+  * \brief A naive preconditioner which approximates any matrix as the identity matrix
   *
   * \sa class DiagonalPreconditioner
   */
diff --git a/Eigen/src/IterativeLinearSolvers/BiCGSTAB.h b/Eigen/src/IterativeLinearSolvers/BiCGSTAB.h
index 798f85da5..574b47384 100644
--- a/Eigen/src/IterativeLinearSolvers/BiCGSTAB.h
+++ b/Eigen/src/IterativeLinearSolvers/BiCGSTAB.h
@@ -115,7 +115,8 @@ struct traits<BiCGSTAB<_MatrixType,_Preconditioner> >
 
 }
 
-/** \brief A bi conjugate gradient stabilized solver for sparse square problems
+/** \ingroup IterativeLinearSolvers_Module
+  * \brief A bi conjugate gradient stabilized solver for sparse square problems
   *
   * This class allows to solve for A.x = b sparse linear problems using a bi conjugate gradient
   * stabilized algorithm. The vectors x and b can be either dense or sparse.
diff --git a/Eigen/src/IterativeLinearSolvers/ConjugateGradient.h b/Eigen/src/IterativeLinearSolvers/ConjugateGradient.h
index 35b89404a..8b3c93bf1 100644
--- a/Eigen/src/IterativeLinearSolvers/ConjugateGradient.h
+++ b/Eigen/src/IterativeLinearSolvers/ConjugateGradient.h
@@ -99,7 +99,8 @@ struct traits<ConjugateGradient<_MatrixType,_UpLo,_Preconditioner> >
 
 }
 
-/** \brief A conjugate gradient solver for sparse self-adjoint problems
+/** \ingroup IterativeLinearSolvers_Module
+  * \brief A conjugate gradient solver for sparse self-adjoint problems
   *
   * This class allows to solve for A.x = b sparse linear problems using a conjugate gradient algorithm.
   * The sparse matrix A must be selfadjoint. The vectors x and b can be either dense or sparse.
diff --git a/Eigen/src/IterativeLinearSolvers/IterativeSolverBase.h b/Eigen/src/IterativeLinearSolvers/IterativeSolverBase.h
index 5e8bbd3e2..9a4eca1a1 100644
--- a/Eigen/src/IterativeLinearSolvers/IterativeSolverBase.h
+++ b/Eigen/src/IterativeLinearSolvers/IterativeSolverBase.h
@@ -26,7 +26,8 @@
 #define EIGEN_ITERATIVE_SOLVER_BASE_H
 
 
-/** \brief Base class for linear iterative solvers
+/** \ingroup IterativeLinearSolvers_Module
+  * \brief Base class for linear iterative solvers
   *
   * \sa class SimplicialCholesky, DiagonalPreconditioner, IdentityPreconditioner
   */
diff --git a/Eigen/src/SparseCholesky/SimplicialCholesky.h b/Eigen/src/SparseCholesky/SimplicialCholesky.h
index b9bed5d01..3206dd0ab 100644
--- a/Eigen/src/SparseCholesky/SimplicialCholesky.h
+++ b/Eigen/src/SparseCholesky/SimplicialCholesky.h
@@ -68,7 +68,8 @@ enum SimplicialCholeskyMode {
   SimplicialCholeskyLDLt
 };
 
-/** \brief A direct sparse Cholesky factorizations
+/** \ingroup SparseCholesky_Module
+  * \brief A direct sparse Cholesky factorizations
   *
   * These classes provide LL^T and LDL^T Cholesky factorizations of sparse matrices that are
   * selfadjoint and positive definite. The factorization allows for solving A.X = B where
@@ -93,6 +94,7 @@ class SimplicialCholeskyBase
 
   public:
 
+    /** Default constructor */
     SimplicialCholeskyBase()
       : m_info(Success), m_isInitialized(false)
     {}
@@ -274,54 +276,28 @@ template<typename _MatrixType, int _UpLo> struct traits<SimplicialLLt<_MatrixTyp
 {
   typedef _MatrixType MatrixType;
   enum { UpLo = _UpLo };
-  typedef typename MatrixType::Scalar                             Scalar;
-  typedef typename MatrixType::Index                              Index;
-  typedef SparseMatrix<Scalar, ColMajor, Index>          CholMatrixType;
-  typedef SparseTriangularView<CholMatrixType, Eigen::Lower>   MatrixL;
+  typedef typename MatrixType::Scalar                         Scalar;
+  typedef typename MatrixType::Index                          Index;
+  typedef SparseMatrix<Scalar, ColMajor, Index>               CholMatrixType;
+  typedef SparseTriangularView<CholMatrixType, Eigen::Lower>  MatrixL;
   typedef SparseTriangularView<typename CholMatrixType::AdjointReturnType, Eigen::Upper>   MatrixU;
   inline static MatrixL getL(const MatrixType& m) { return m; }
   inline static MatrixU getU(const MatrixType& m) { return m.adjoint(); }
 };
 
-//template<typename _MatrixType> struct traits<SimplicialLLt<_MatrixType,Upper> >
-//{
-//  typedef _MatrixType MatrixType;
-//  enum { UpLo = Upper };
-//  typedef typename MatrixType::Scalar                             Scalar;
-//  typedef typename MatrixType::Index                              Index;
-//  typedef SparseMatrix<Scalar, ColMajor, Index>          CholMatrixType;
-//  typedef TriangularView<CholMatrixType, Eigen::Lower>   MatrixL;
-//  typedef TriangularView<CholMatrixType, Eigen::Upper>   MatrixU;
-//  inline static MatrixL getL(const MatrixType& m) { return m.adjoint(); }
-//  inline static MatrixU getU(const MatrixType& m) { return m; }
-//};
-
 template<typename _MatrixType,int _UpLo> struct traits<SimplicialLDLt<_MatrixType,_UpLo> >
 {
   typedef _MatrixType MatrixType;
   enum { UpLo = _UpLo };
-  typedef typename MatrixType::Scalar                               Scalar;
-  typedef typename MatrixType::Index                                Index;
-  typedef SparseMatrix<Scalar, ColMajor, Index>            CholMatrixType;
-  typedef SparseTriangularView<CholMatrixType, Eigen::UnitLower> MatrixL;
+  typedef typename MatrixType::Scalar                             Scalar;
+  typedef typename MatrixType::Index                              Index;
+  typedef SparseMatrix<Scalar, ColMajor, Index>                   CholMatrixType;
+  typedef SparseTriangularView<CholMatrixType, Eigen::UnitLower>  MatrixL;
   typedef SparseTriangularView<typename CholMatrixType::AdjointReturnType, Eigen::UnitUpper> MatrixU;
   inline static MatrixL getL(const MatrixType& m) { return m; }
   inline static MatrixU getU(const MatrixType& m) { return m.adjoint(); }
 };
 
-//template<typename _MatrixType> struct traits<SimplicialLDLt<_MatrixType,Upper> >
-//{
-//  typedef _MatrixType MatrixType;
-//  enum { UpLo = Upper };
-//  typedef typename MatrixType::Scalar                               Scalar;
-//  typedef typename MatrixType::Index                                Index;
-//  typedef SparseMatrix<Scalar, ColMajor, Index>            CholMatrixType;
-//  typedef TriangularView<CholMatrixType, Eigen::UnitLower> MatrixL;
-//  typedef TriangularView<CholMatrixType, Eigen::UnitUpper> MatrixU;
-//  inline static MatrixL getL(const MatrixType& m) { return m.adjoint(); }
-//  inline static MatrixU getU(const MatrixType& m) { return m; }
-//};
-
 template<typename _MatrixType, int _UpLo> struct traits<SimplicialCholesky<_MatrixType,_UpLo> >
 {
   typedef _MatrixType MatrixType;
@@ -330,7 +306,8 @@ template<typename _MatrixType, int _UpLo> struct traits<SimplicialCholesky<_Matr
 
 }
 
-/** \class SimplicialLLt
+/** \ingroup SparseCholesky_Module
+  * \class SimplicialLLt
   * \brief A direct sparse LLt Cholesky factorizations
   *
   * This class provides a LL^T Cholesky factorizations of sparse matrices that are
@@ -359,15 +336,19 @@ public:
     typedef typename Traits::MatrixL  MatrixL;
     typedef typename Traits::MatrixU  MatrixU;
 public:
+    /** Default constructor */
     SimplicialLLt() : Base() {}
+    /** Constructs and performs the LLt factorization of \a matrix */
     SimplicialLLt(const MatrixType& matrix)
         : Base(matrix) {}
 
+    /** \returns an expression of the factor L */
     inline const MatrixL matrixL() const {
         eigen_assert(Base::m_factorizationIsOk && "Simplicial LLt not factorized");
         return Traits::getL(Base::m_matrix);
     }
 
+    /** \returns an expression of the factor U (= L^*) */
     inline const MatrixU matrixU() const {
         eigen_assert(Base::m_factorizationIsOk && "Simplicial LLt not factorized");
         return Traits::getU(Base::m_matrix);
@@ -395,6 +376,7 @@ public:
       Base::template factorize<false>(a);
     }
 
+    /** \returns the determinant of the underlying matrix from the current factorization */
     Scalar determinant() const
     {
       Scalar detL = Diagonal<const CholMatrixType>(Base::m_matrix).prod();
@@ -402,7 +384,8 @@ public:
     }
 };
 
-/** \class SimplicialLDLt
+/** \ingroup SparseCholesky_Module
+  * \class SimplicialLDLt
   * \brief A direct sparse LDLt Cholesky factorizations without square root.
   *
   * This class provides a LDL^T Cholesky factorizations without square root of sparse matrices that are
@@ -431,19 +414,25 @@ public:
     typedef typename Traits::MatrixL  MatrixL;
     typedef typename Traits::MatrixU  MatrixU;
 public:
+    /** Default constructor */
     SimplicialLDLt() : Base() {}
+
+    /** Constructs and performs the LLt factorization of \a matrix */
     SimplicialLDLt(const MatrixType& matrix)
         : Base(matrix) {}
 
+    /** \returns a vector expression of the diagonal D */
     inline const VectorType vectorD() const {
         eigen_assert(Base::m_factorizationIsOk && "Simplicial LDLt not factorized");
         return Base::m_diag;
     }
+    /** \returns an expression of the factor L */
     inline const MatrixL matrixL() const {
         eigen_assert(Base::m_factorizationIsOk && "Simplicial LDLt not factorized");
         return Traits::getL(Base::m_matrix);
     }
 
+    /** \returns an expression of the factor U (= L^*) */
     inline const MatrixU matrixU() const {
         eigen_assert(Base::m_factorizationIsOk && "Simplicial LDLt not factorized");
         return Traits::getU(Base::m_matrix);
@@ -471,14 +460,17 @@ public:
       Base::template factorize<true>(a);
     }
 
+    /** \returns the determinant of the underlying matrix from the current factorization */
     Scalar determinant() const
     {
       return Base::m_diag.prod();
     }
 };
 
-/** \class SimplicialCholesky
-  * \deprecated use SimplicialLDLt or class SimplicialLLt
+/** \deprecated use SimplicialLDLt or class SimplicialLLt
+  * \ingroup SparseCholesky_Module
+  * \class SimplicialCholesky
+  *
   * \sa class SimplicialLDLt, class SimplicialLLt
   */
 template<typename _MatrixType, int _UpLo>
diff --git a/Eigen/src/SparseCore/SparseMatrixBase.h b/Eigen/src/SparseCore/SparseMatrixBase.h
index 849e00593..7f5532fd4 100644
--- a/Eigen/src/SparseCore/SparseMatrixBase.h
+++ b/Eigen/src/SparseCore/SparseMatrixBase.h
@@ -154,12 +154,12 @@ template<typename Derived> class SparseMatrixBase : public EigenBase<Derived>
     { return *static_cast<Derived*>(const_cast<SparseMatrixBase*>(this)); }
 #endif // not EIGEN_PARSED_BY_DOXYGEN
 
-    /** \returns the number of rows. \sa cols(), RowsAtCompileTime */
+    /** \returns the number of rows. \sa cols() */
     inline Index rows() const { return derived().rows(); }
-    /** \returns the number of columns. \sa rows(), ColsAtCompileTime*/
+    /** \returns the number of columns. \sa rows() */
     inline Index cols() const { return derived().cols(); }
     /** \returns the number of coefficients, which is \a rows()*cols().
-      * \sa rows(), cols(), SizeAtCompileTime. */
+      * \sa rows(), cols(). */
     inline Index size() const { return rows() * cols(); }
     /** \returns the number of nonzero coefficients which is in practice the number
       * of stored coefficients. */
@@ -272,9 +272,6 @@ template<typename Derived> class SparseMatrixBase : public EigenBase<Derived>
     template<typename Lhs, typename Rhs>
     inline Derived& operator=(const SparseSparseProduct<Lhs,Rhs>& product);
 
-    template<typename Lhs, typename Rhs>
-    inline void _experimentalNewProduct(const Lhs& lhs, const Rhs& rhs);
-
     friend std::ostream & operator << (std::ostream & s, const SparseMatrixBase& m)
     {
       if (Flags&RowMajorBit)
diff --git a/Eigen/src/SparseCore/SparseProduct.h b/Eigen/src/SparseCore/SparseProduct.h
index f3b9b40b0..1c7acc307 100644
--- a/Eigen/src/SparseCore/SparseProduct.h
+++ b/Eigen/src/SparseCore/SparseProduct.h
@@ -175,7 +175,17 @@ inline Derived& SparseMatrixBase<Derived>::operator=(const SparseSparseProduct<L
   return derived();
 }
 
-// sparse * sparse
+/** \returns an expression of the product of two sparse matrices.
+  * By default a conservative product preserving the symbolic non zeros is performed.
+  * The automatic pruning of the small values can be achieved by calling the pruned() function
+  * in which case a totally different product algorithm is employed:
+  * \code
+  * C = (A*B).pruned();             // supress numerical zeros (exact)
+  * C = (A*B).pruned(ref);
+  * C = (A*B).pruned(ref,epsilon);
+  * \endcode
+  * where \c ref is a meaningful non zero reference value.
+  * */
 template<typename Derived>
 template<typename OtherDerived>
 inline const typename SparseSparseProductReturnType<Derived,OtherDerived>::Type
diff --git a/Eigen/src/SuperLUSupport/SuperLUSupport.h b/Eigen/src/SuperLUSupport/SuperLUSupport.h
index 5f87b1f37..2d8584f65 100644
--- a/Eigen/src/SuperLUSupport/SuperLUSupport.h
+++ b/Eigen/src/SuperLUSupport/SuperLUSupport.h
@@ -799,6 +799,10 @@ typename SuperLU<MatrixType>::Scalar SuperLU<MatrixType>::determinant() const
     return det;
 }
 
+#ifdef EIGEN_PARSED_BY_DOXYGEN
+#define EIGEN_SUPERLU_HAS_ILU
+#endif
+
 #ifdef EIGEN_SUPERLU_HAS_ILU
 
 /** \ingroup SuperLUSupport_Module
@@ -808,6 +812,8 @@ typename SuperLU<MatrixType>::Scalar SuperLU<MatrixType>::determinant() const
   * This class allows to solve for an approximate solution of A.X = B sparse linear problems via an incomplete LU factorization
   * using the SuperLU library. This class is aimed to be used as a preconditioner of the iterative linear solvers.
   *
+  * \warning This class requires SuperLU 4 or later.
+  *
   * \tparam _MatrixType the type of the sparse matrix A, it must be a SparseMatrix<>
   *
   * \sa \ref TutorialSparseDirectSolvers, class ConjugateGradient, class BiCGSTAB