diff options
author | Desire NUENTSA <desire.nuentsa_wakam@inria.fr> | 2012-09-25 11:48:18 +0200 |
---|---|---|
committer | Desire NUENTSA <desire.nuentsa_wakam@inria.fr> | 2012-09-25 11:48:18 +0200 |
commit | 15a9f6b9c1d2673f5c319c826794c4bce0282696 (patch) | |
tree | a25113e80d0175b2d0c214ec2f440615f3000748 /Eigen | |
parent | 5a3f49036b8ba786e018150b462a226b183290b0 (diff) |
Doc for sparseLU
Diffstat (limited to 'Eigen')
-rw-r--r-- | Eigen/src/SparseLU/SparseLU.h | 59 |
1 files changed, 51 insertions, 8 deletions
diff --git a/Eigen/src/SparseLU/SparseLU.h b/Eigen/src/SparseLU/SparseLU.h index 6d0698a3d..6f4458a26 100644 --- a/Eigen/src/SparseLU/SparseLU.h +++ b/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. |