Doc for sparseLU

Eigen/src/SparseLU/SparseLU.h

@@ -24,9 +24,50 @@ namespace Eigen {
  * \ingroup SparseLU_Module
  * \brief Sparse supernodal LU factorization for general matrices
  * 
- * This class implements the supernodal LU factorization for general matrices. 
+ * This class implements the supernodal LU factorization for general matrices.
+ * It uses the main techniques from the sequential SuperLU package 
+ * (http://crd-legacy.lbl.gov/~xiaoye/SuperLU/). It handles transparently real 
+ * and complex arithmetics with single and double precision, depending on the 
+ * scalar type of your input matrix. 
+ * The code has been optimized to provide BLAS-3 operations during supernode-panel updates. 
+ * It benefits directly from the built-in high-performant Eigen BLAS routines. 
+ * Moreover, when the size of a supernode is very small, the BLAS calls are avoided to 
+ * enable a better optimization from the compiler. For best performance, 
+ * you should compile it with NDEBUG flag to avoid the numerous bounds checking on vectors. 
+ * 
+ * An important parameter of this class is the ordering method. It is used to reorder the columns 
+ * (and eventually the rows) of the matrix to reduce the number of new elements that are created during 
+ * numerical factorization. The cheapest method available is COLAMD. 
+ * See  \link Ordering_Modules the Ordering module \endlink for the list of 
+ * built-in and external ordering methods. 
+ *
+ * Simple example with key steps 
+ * \code
+ * VectorXd x(n), b(n);
+ * SparseMatrix<double, ColMajor> A;
+ * SparseLU<SparseMatrix<scalar, ColMajor>, COLAMDOrdering<int> >   solver;
+ * // fill A and b;
+ * // Compute the ordering permutation vector from the structural pattern of A
+ * solver.analyzePattern(A); 
+ * // Compute the numerical factorization 
+ * solver.factorize(A); 
+ * //Use the factors to solve the linear system 
+ * x = solver.solve(b); 
+ * \endcode
+ * 
+ * \WARNING The input matrix A should be in a \b compressed and \b column-major form.
+ * Otherwise an expensive copy will be made. You can call the inexpensive makeCompressed() to get a compressed matrix.
+ * 
+ * \NOTE Unlike the initial SuperLU implementation, there is no step to equilibrate the matrix. 
+ * For badly scaled matrices, this step can be useful to reduce the pivoting during factorization. 
+ * If this is the case for your matrices, you can try the basic scaling method in \ref Scaling. 
  * 
  * \tparam _MatrixType The type of the sparse matrix. It must be a column-major SparseMatrix<>
+ * \tparam _OrderingType The ordering method to use, either AMD, COLAMD or METIS
+ * 
+ * 
+ * \sa \ref TutorialSparseDirectSolvers
+ * \sa \ref Ordering_Modules
  */
 template <typename _MatrixType, typename _OrderingType>
 class SparseLU
@@ -247,13 +288,13 @@ class SparseLU
 
 // Functions needed by the anaysis phase
 /** 
- * Compute the column permutation to minimize the fill-in (file amd.c )
+ * Compute the column permutation to minimize the fill-in
  * 
  *  - Apply this permutation to the input matrix - 
  * 
- *  - Compute the column elimination tree on the permuted matrix (file Eigen_Coletree.h)
+ *  - Compute the column elimination tree on the permuted matrix 
  * 
- *  - Postorder the elimination tree and the column permutation (file Eigen_Coletree.h)
+ *  - Postorder the elimination tree and the column permutation
  * 
  */
 template <typename MatrixType, typename OrderingType>
@@ -315,15 +356,17 @@ void SparseLU<MatrixType, OrderingType>::analyzePattern(const MatrixType& mat)
 /** 
  *  - Numerical factorization 
  *  - Interleaved with the symbolic factorization 
- * \tparam MatrixType The type of the matrix, it should be a column-major sparse matrix
- * \return info where
- *  : successful exit
- *    = 0: successful exit
+ * On exit,  info is 
+ * 
+ *    = 0: successful factorization
+ * 
  *    > 0: if info = i, and i is
+ * 
  *       <= A->ncol: U(i,i) is exactly zero. The factorization has
  *          been completed, but the factor U is exactly singular,
  *          and division by zero will occur if it is used to solve a
  *          system of equations.
+ * 
  *       > A->ncol: number of bytes allocated when memory allocation
  *         failure occurred, plus A->ncol. If lwork = -1, it is
  *         the estimated amount of space needed, plus A->ncol.  

bench/spbench/test_sparseLU.cpp

@@ -28,7 +28,7 @@ int main(int argc, char **args)
 //   SparseLU<SparseMatrix<scalar, ColMajor>, MetisOrdering<int> > solver; 
 //   std::cout<< "ORDERING : METIS\n"; 
 // #else
-  SparseLU<SparseMatrix<scalar, ColMajor>, COLAMDOrdering<int> >   solver;
+  SparseLU<SparseMatrix<scalar, ColMajor>, COLAMDOrdering<int> >  solver;
   std::cout<< "ORDERING : COLAMD\n"; 
 // #endif