Eigen  3.4.90 (git rev a4098ac676528a83cfb73d4d26ce1b42ec05f47c)
Eigen::SparseLU< MatrixType_, OrderingType_ > Class Template Reference

Detailed Description

template<typename MatrixType_, typename OrderingType_>
class Eigen::SparseLU< MatrixType_, OrderingType_ >

Sparse 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 arithmetic 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 the OrderingMethods module for the list of built-in and external ordering methods.

Simple example with key steps

VectorXd x(n), b(n);
SparseMatrix<double> A;
SparseLU<SparseMatrix<double>, 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);
Warning
The input matrix A should be in a compressed and 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 at "unsupported/Eigen/src/IterativeSolvers/Scaling.h"
Template Parameters
MatrixType_The type of the sparse matrix. It must be a column-major SparseMatrix<>
OrderingType_The ordering method to use, either AMD, COLAMD or METIS. Default is COLMAD

This class follows the sparse solver concept .

See also
Sparse solver concept
OrderingMethods module
+ Inheritance diagram for Eigen::SparseLU< MatrixType_, OrderingType_ >:

Public Member Functions

Scalar absDeterminant ()
 
const SparseLUTransposeView< true, SparseLU< MatrixType_, OrderingType_ > > adjoint ()
 
void analyzePattern (const MatrixType &matrix)
 
const PermutationTypecolsPermutation () const
 
void compute (const MatrixType &matrix)
 
Scalar determinant ()
 
void factorize (const MatrixType &matrix)
 
ComputationInfo info () const
 Reports whether previous computation was successful. More...
 
void isSymmetric (bool sym)
 
std::string lastErrorMessage () const
 
Scalar logAbsDeterminant () const
 
SparseLUMatrixLReturnType< SCMatrix > matrixL () const
 
SparseLUMatrixUReturnType< SCMatrix, Map< SparseMatrix< Scalar, ColMajor, StorageIndex > > > matrixU () const
 
const PermutationTyperowsPermutation () const
 
void setPivotThreshold (const RealScalar &thresh)
 
Scalar signDeterminant ()
 
template<typename Rhs >
const Solve< SparseLU, Rhs > solve (const MatrixBase< Rhs > &B) const
 
const SparseLUTransposeView< false, SparseLU< MatrixType_, OrderingType_ > > transpose ()
 
- Public Member Functions inherited from Eigen::SparseSolverBase< SparseLU< MatrixType_, OrderingType_ > >
const Solve< SparseLU< MatrixType_, OrderingType_ >, Rhs > solve (const MatrixBase< Rhs > &b) const
 
const Solve< SparseLU< MatrixType_, OrderingType_ >, Rhs > solve (const SparseMatrixBase< Rhs > &b) const
 
 SparseSolverBase ()
 

Member Function Documentation

◆ absDeterminant()

template<typename MatrixType_ , typename OrderingType_ >
Scalar Eigen::SparseLU< MatrixType_, OrderingType_ >::absDeterminant ( )
inline
Returns
the absolute value of the determinant of the matrix of which *this is the QR decomposition.
Warning
a determinant can be very big or small, so for matrices of large enough dimension, there is a risk of overflow/underflow. One way to work around that is to use logAbsDeterminant() instead.
See also
logAbsDeterminant(), signDeterminant()

◆ adjoint()

template<typename MatrixType_ , typename OrderingType_ >
const SparseLUTransposeView< true, SparseLU< MatrixType_, OrderingType_ > > Eigen::SparseLU< MatrixType_, OrderingType_ >::adjoint ( )
inline
Returns
an expression of the adjoint of the factored matrix

A typical usage is to solve for the adjoint problem A' x = b:

solver.compute(A);
x = solver.adjoint().solve(b);

For real scalar types, this function is equivalent to transpose().

See also
transpose(), solve()

◆ analyzePattern()

template<typename MatrixType , typename OrderingType >
void Eigen::SparseLU< MatrixType, OrderingType >::analyzePattern ( const MatrixType &  mat)

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
  • Postorder the elimination tree and the column permutation

◆ colsPermutation()

template<typename MatrixType_ , typename OrderingType_ >
const PermutationType & Eigen::SparseLU< MatrixType_, OrderingType_ >::colsPermutation ( ) const
inline
Returns
a reference to the column matrix permutation \( P_c^T \) such that \(P_r A P_c^T = L U\)
See also
rowsPermutation()

◆ compute()

template<typename MatrixType_ , typename OrderingType_ >
void Eigen::SparseLU< MatrixType_, OrderingType_ >::compute ( const MatrixType &  matrix)
inline

Compute the symbolic and numeric factorization of the input sparse matrix. The input matrix should be in column-major storage.

◆ determinant()

template<typename MatrixType_ , typename OrderingType_ >
Scalar Eigen::SparseLU< MatrixType_, OrderingType_ >::determinant ( )
inline
Returns
The determinant of the matrix.
See also
absDeterminant(), logAbsDeterminant()

◆ factorize()

template<typename MatrixType , typename OrderingType >
void Eigen::SparseLU< MatrixType, OrderingType >::factorize ( const MatrixType &  matrix)
  • Numerical factorization
  • Interleaved with the symbolic factorization 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.

◆ info()

template<typename MatrixType_ , typename OrderingType_ >
ComputationInfo Eigen::SparseLU< MatrixType_, OrderingType_ >::info ( ) const
inline

Reports whether previous computation was successful.

Returns
Success if computation was successful, NumericalIssue if the LU factorization reports a problem, zero diagonal for instance InvalidInput if the input matrix is invalid
See also
iparm()

◆ isSymmetric()

template<typename MatrixType_ , typename OrderingType_ >
void Eigen::SparseLU< MatrixType_, OrderingType_ >::isSymmetric ( bool  sym)
inline

Indicate that the pattern of the input matrix is symmetric

◆ lastErrorMessage()

template<typename MatrixType_ , typename OrderingType_ >
std::string Eigen::SparseLU< MatrixType_, OrderingType_ >::lastErrorMessage ( ) const
inline
Returns
A string describing the type of error

◆ logAbsDeterminant()

template<typename MatrixType_ , typename OrderingType_ >
Scalar Eigen::SparseLU< MatrixType_, OrderingType_ >::logAbsDeterminant ( ) const
inline
Returns
the natural log of the absolute value of the determinant of the matrix of which **this is the QR decomposition
Note
This method is useful to work around the risk of overflow/underflow that's inherent to the determinant computation.
See also
absDeterminant(), signDeterminant()

◆ matrixL()

template<typename MatrixType_ , typename OrderingType_ >
SparseLUMatrixLReturnType< SCMatrix > Eigen::SparseLU< MatrixType_, OrderingType_ >::matrixL ( ) const
inline
Returns
an expression of the matrix L, internally stored as supernodes The only operation available with this expression is the triangular solve
y = b; matrixL().solveInPlace(y);
SparseLUMatrixLReturnType< SCMatrix > matrixL() const
Definition: SparseLU.h:245

◆ matrixU()

template<typename MatrixType_ , typename OrderingType_ >
SparseLUMatrixUReturnType< SCMatrix, Map< SparseMatrix< Scalar, ColMajor, StorageIndex > > > Eigen::SparseLU< MatrixType_, OrderingType_ >::matrixU ( ) const
inline
Returns
an expression of the matrix U, The only operation available with this expression is the triangular solve
y = b; matrixU().solveInPlace(y);
SparseLUMatrixUReturnType< SCMatrix, Map< SparseMatrix< Scalar, ColMajor, StorageIndex > > > matrixU() const
Definition: SparseLU.h:255

◆ rowsPermutation()

template<typename MatrixType_ , typename OrderingType_ >
const PermutationType & Eigen::SparseLU< MatrixType_, OrderingType_ >::rowsPermutation ( ) const
inline
Returns
a reference to the row matrix permutation \( P_r \) such that \(P_r A P_c^T = L U\)
See also
colsPermutation()

◆ setPivotThreshold()

template<typename MatrixType_ , typename OrderingType_ >
void Eigen::SparseLU< MatrixType_, OrderingType_ >::setPivotThreshold ( const RealScalar &  thresh)
inline

Set the threshold used for a diagonal entry to be an acceptable pivot.

◆ signDeterminant()

template<typename MatrixType_ , typename OrderingType_ >
Scalar Eigen::SparseLU< MatrixType_, OrderingType_ >::signDeterminant ( )
inline
Returns
A number representing the sign of the determinant
See also
absDeterminant(), logAbsDeterminant()

◆ solve()

template<typename MatrixType_ , typename OrderingType_ >
template<typename Rhs >
const Solve< SparseLU, Rhs > Eigen::SparseLU< MatrixType_, OrderingType_ >::solve ( const MatrixBase< Rhs > &  B) const
inline
Returns
the solution X of \( A X = B \) using the current decomposition of A.
Warning
the destination matrix X in X = this->solve(B) must be colmun-major.
See also
compute()

◆ transpose()

template<typename MatrixType_ , typename OrderingType_ >
const SparseLUTransposeView< false, SparseLU< MatrixType_, OrderingType_ > > Eigen::SparseLU< MatrixType_, OrderingType_ >::transpose ( )
inline
Returns
an expression of the transposed of the factored matrix.

A typical usage is to solve for the transposed problem A^T x = b:

solver.compute(A);
x = solver.transpose().solve(b);
See also
adjoint(), solve()

The documentation for this class was generated from the following file: