Sparse supernodal LU factorization for general matrices. More...

#include <SparseLU.h>

Public Types
enum	{ ColsAtCompileTime = MatrixType::ColsAtCompileTime, MaxColsAtCompileTime = MatrixType::MaxColsAtCompileTime }

typedef internal::SparseLUImpl< Scalar, StorageIndex >	Base

typedef Matrix< StorageIndex, Dynamic, 1 >	IndexVector

typedef _MatrixType	MatrixType

typedef SparseMatrix< Scalar, ColMajor, StorageIndex >	NCMatrix

typedef _OrderingType	OrderingType

typedef PermutationMatrix< Dynamic, Dynamic, StorageIndex >	PermutationType

typedef MatrixType::RealScalar	RealScalar

typedef MatrixType::Scalar	Scalar

typedef Matrix< Scalar, Dynamic, 1 >	ScalarVector

typedef internal::MappedSuperNodalMatrix< Scalar, StorageIndex >	SCMatrix

typedef MatrixType::StorageIndex	StorageIndex

Public Member Functions
template<typename Rhs , typename Dest >
bool	_solve_impl (const MatrixBase< Rhs > &B, MatrixBase< Dest > &X_base) const

template<typename Rhs , typename Dest >
void	_solve_impl (const SparseMatrixBase< Rhs > &b, SparseMatrixBase< Dest > &dest) const

Scalar	absDeterminant ()

void	analyzePattern (const MatrixType &matrix)

Index	cols () const

const PermutationType &	colsPermutation () 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, MappedSparseMatrix< Scalar, ColMajor, StorageIndex > >	matrixU () const

Index	rows () const

const PermutationType &	rowsPermutation () const

void	setPivotThreshold (const RealScalar &thresh)

Scalar	signDeterminant ()

void	simplicialfactorize (const MatrixType &matrix)

	SparseLU ()

	SparseLU (const MatrixType &matrix)

	~SparseLU ()

Protected Types
typedef SparseSolverBase< SparseLU< _MatrixType, _OrderingType > >	APIBase

Protected Member Functions
void	initperfvalues ()

Protected Attributes
bool	m_analysisIsOk

Index	m_detPermC

Index	m_detPermR

RealScalar	m_diagpivotthresh

IndexVector	m_etree

bool	m_factorizationIsOk

Base::GlobalLU_t	m_glu

ComputationInfo	m_info

bool	m_isInitialized

std::string	m_lastError

SCMatrix	m_Lstore

NCMatrix	m_mat

Index	m_nnzL

Index	m_nnzU

internal::perfvalues	m_perfv

PermutationType	m_perm_c

PermutationType	m_perm_r

bool	m_symmetricmode

MappedSparseMatrix< Scalar, ColMajor, StorageIndex >	m_Ustore

Private Member Functions
	SparseLU (const SparseLU &)

Detailed Description

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 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 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, ColMajor> A;
SparseLU<SparseMatrix<scalar, ColMajor>, COLAMDOrdering<Index> >   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

\implsparsesolverconcept

See also: TutorialSparseSolverConcept; OrderingMethods_Module

Definition at line 17 of file SparseLU.h.

Member Typedef Documentation

◆ APIBase

typedef SparseSolverBase<SparseLU<_MatrixType,_OrderingType> > Eigen::SparseLU::APIBase

protected

Definition at line 77 of file SparseLU.h.

◆ Base

typedef internal::SparseLUImpl<Scalar, StorageIndex> Eigen::SparseLU::Base

Definition at line 92 of file SparseLU.h.

◆ IndexVector

typedef Matrix<StorageIndex,Dynamic,1> Eigen::SparseLU::IndexVector

Definition at line 90 of file SparseLU.h.

◆ MatrixType

typedef _MatrixType Eigen::SparseLU::MatrixType

Definition at line 82 of file SparseLU.h.

◆ NCMatrix

typedef SparseMatrix<Scalar,ColMajor,StorageIndex> Eigen::SparseLU::NCMatrix

Definition at line 87 of file SparseLU.h.

◆ OrderingType

typedef _OrderingType Eigen::SparseLU::OrderingType

Definition at line 83 of file SparseLU.h.

◆ PermutationType

typedef PermutationMatrix<Dynamic, Dynamic, StorageIndex> Eigen::SparseLU::PermutationType

Definition at line 91 of file SparseLU.h.

◆ RealScalar

typedef MatrixType::RealScalar Eigen::SparseLU::RealScalar

Definition at line 85 of file SparseLU.h.

◆ Scalar

typedef MatrixType::Scalar Eigen::SparseLU::Scalar

Definition at line 84 of file SparseLU.h.

◆ ScalarVector

typedef Matrix<Scalar,Dynamic,1> Eigen::SparseLU::ScalarVector

Definition at line 89 of file SparseLU.h.

◆ SCMatrix

typedef internal::MappedSuperNodalMatrix<Scalar, StorageIndex> Eigen::SparseLU::SCMatrix

Definition at line 88 of file SparseLU.h.

◆ StorageIndex

typedef MatrixType::StorageIndex Eigen::SparseLU::StorageIndex

Definition at line 86 of file SparseLU.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
ColsAtCompileTime
MaxColsAtCompileTime

Definition at line 94 of file SparseLU.h.

Constructor & Destructor Documentation

◆ SparseLU() [1/3]

Eigen::SparseLU::SparseLU ( )

inline

Definition at line 100 of file SparseLU.h.

◆ SparseLU() [2/3]

Eigen::SparseLU::SparseLU ( const MatrixType & matrix )

inlineexplicit

Definition at line 104 of file SparseLU.h.

◆ ~SparseLU()

Eigen::SparseLU::~SparseLU ( )

inline

Definition at line 111 of file SparseLU.h.

◆ SparseLU() [3/3]

Eigen::SparseLU::SparseLU ( const SparseLU & )

private

Member Function Documentation

◆ _solve_impl() [1/2]

template<typename Rhs , typename Dest >

bool Eigen::SparseLU::_solve_impl	(	const MatrixBase< Rhs > &	B,
		MatrixBase< Dest > &	X_base
	)		const

inline

Definition at line 217 of file SparseLU.h.

◆ _solve_impl() [2/2]

template<typename Rhs , typename Dest >

void Eigen::SparseSolverBase< Derived >::_solve_impl	(	typename Rhs	,
		typename Dest
	)

inline

Definition at line 111 of file SparseSolverBase.h.

◆ absDeterminant()

Scalar Eigen::SparseLU::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()

Definition at line 253 of file SparseLU.h.

◆ analyzePattern()

void Eigen::SparseLU::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

Definition at line 411 of file SparseLU.h.

◆ cols()

Index Eigen::SparseLU::cols ( ) const

inline

Definition at line 133 of file SparseLU.h.

◆ colsPermutation()

const PermutationType& Eigen::SparseLU::colsPermutation ( ) const

inline

Returns: a reference to the column matrix permutation such that

See also: rowsPermutation()

Definition at line 173 of file SparseLU.h.

◆ compute()

void Eigen::SparseLU::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.

Definition at line 124 of file SparseLU.h.

◆ determinant()

Scalar Eigen::SparseLU::determinant ( )

inline

Returns: The determinant of the matrix.

See also: absDeterminant(), logAbsDeterminant()

Definition at line 337 of file SparseLU.h.

◆ factorize()

void Eigen::SparseLU::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.

Definition at line 496 of file SparseLU.h.

◆ info()

ComputationInfo Eigen::SparseLU::info ( ) const

inline

Reports whether previous computation was successful.

Returns: Success if computation was succesful, NumericalIssue if the LU factorization reports a problem, zero diagonal for instance InvalidInput if the input matrix is invalid

See also: iparm()

Definition at line 202 of file SparseLU.h.

◆ initperfvalues()

void Eigen::SparseLU::initperfvalues ( )

inlineprotected

Definition at line 360 of file SparseLU.h.

◆ isSymmetric()

void Eigen::SparseLU::isSymmetric ( bool sym )

inline

Indicate that the pattern of the input matrix is symmetric

Definition at line 135 of file SparseLU.h.

◆ lastErrorMessage()

std::string Eigen::SparseLU::lastErrorMessage ( ) const

inline

Returns: A string describing the type of error

Definition at line 211 of file SparseLU.h.

◆ logAbsDeterminant()

Scalar Eigen::SparseLU::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()

Definition at line 283 of file SparseLU.h.

◆ matrixL()

SparseLUMatrixLReturnType<SCMatrix> Eigen::SparseLU::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);

Definition at line 146 of file SparseLU.h.

◆ matrixU()

SparseLUMatrixUReturnType<SCMatrix,MappedSparseMatrix<Scalar,ColMajor,StorageIndex> > Eigen::SparseLU::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);

Definition at line 156 of file SparseLU.h.

◆ rows()

Index Eigen::SparseLU::rows ( ) const

inline

Definition at line 132 of file SparseLU.h.

◆ rowsPermutation()

const PermutationType& Eigen::SparseLU::rowsPermutation ( ) const

inline

Returns: a reference to the row matrix permutation such that

See also: colsPermutation()

Definition at line 165 of file SparseLU.h.

◆ setPivotThreshold()

void Eigen::SparseLU::setPivotThreshold ( const RealScalar & thresh )

inline

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

Definition at line 178 of file SparseLU.h.

◆ signDeterminant()

Scalar Eigen::SparseLU::signDeterminant ( )

inline

Returns: A number representing the sign of the determinant

See also: absDeterminant(), logAbsDeterminant()

Definition at line 309 of file SparseLU.h.

◆ simplicialfactorize()

void Eigen::SparseLU::simplicialfactorize ( const MatrixType & matrix )

Member Data Documentation

◆ m_analysisIsOk

bool Eigen::SparseLU::m_analysisIsOk

protected

Definition at line 373 of file SparseLU.h.

◆ m_detPermC

Index Eigen::SparseLU::m_detPermC

protected

Definition at line 390 of file SparseLU.h.

◆ m_detPermR

Index Eigen::SparseLU::m_detPermR

protected

Definition at line 390 of file SparseLU.h.

◆ m_diagpivotthresh

RealScalar Eigen::SparseLU::m_diagpivotthresh

protected

Definition at line 388 of file SparseLU.h.

◆ m_etree

IndexVector Eigen::SparseLU::m_etree

protected

Definition at line 380 of file SparseLU.h.

◆ m_factorizationIsOk

bool Eigen::SparseLU::m_factorizationIsOk

protected

Definition at line 372 of file SparseLU.h.

◆ m_glu

Base::GlobalLU_t Eigen::SparseLU::m_glu

protected

Definition at line 382 of file SparseLU.h.

◆ m_info

ComputationInfo Eigen::SparseLU::m_info

mutableprotected

Definition at line 371 of file SparseLU.h.

◆ m_isInitialized

bool Eigen::SparseSolverBase< Derived >::m_isInitialized

mutableprotected

Definition at line 119 of file SparseSolverBase.h.

◆ m_lastError

std::string Eigen::SparseLU::m_lastError

protected

Definition at line 374 of file SparseLU.h.

◆ m_Lstore

SCMatrix Eigen::SparseLU::m_Lstore

protected

Definition at line 376 of file SparseLU.h.

◆ m_mat

NCMatrix Eigen::SparseLU::m_mat

protected

Definition at line 375 of file SparseLU.h.

◆ m_nnzL

Index Eigen::SparseLU::m_nnzL

protected

Definition at line 389 of file SparseLU.h.

◆ m_nnzU

Index Eigen::SparseLU::m_nnzU

protected

Definition at line 389 of file SparseLU.h.

◆ m_perfv

internal::perfvalues Eigen::SparseLU::m_perfv

protected

Definition at line 387 of file SparseLU.h.

◆ m_perm_c

PermutationType Eigen::SparseLU::m_perm_c

protected

Definition at line 378 of file SparseLU.h.

◆ m_perm_r

PermutationType Eigen::SparseLU::m_perm_r

protected

Definition at line 379 of file SparseLU.h.

◆ m_symmetricmode

bool Eigen::SparseLU::m_symmetricmode

protected

Definition at line 385 of file SparseLU.h.

◆ m_Ustore

MappedSparseMatrix<Scalar,ColMajor,StorageIndex> Eigen::SparseLU::m_Ustore

protected

Definition at line 377 of file SparseLU.h.

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

SparseLU.h

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ APIBase

◆ Base

◆ IndexVector

◆ MatrixType

◆ NCMatrix

◆ OrderingType

◆ PermutationType

◆ RealScalar

◆ Scalar

◆ ScalarVector

◆ SCMatrix

◆ StorageIndex

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ SparseLU() [1/3]

◆ SparseLU() [2/3]

◆ ~SparseLU()

◆ SparseLU() [3/3]

Member Function Documentation

◆ _solve_impl() [1/2]

◆ _solve_impl() [2/2]

◆ absDeterminant()

◆ analyzePattern()

◆ cols()

◆ colsPermutation()

◆ compute()

◆ determinant()

◆ factorize()

◆ info()

◆ initperfvalues()

◆ isSymmetric()

◆ lastErrorMessage()

◆ logAbsDeterminant()

◆ matrixL()

◆ matrixU()

◆ rows()

◆ rowsPermutation()

◆ setPivotThreshold()

◆ signDeterminant()

◆ simplicialfactorize()

Member Data Documentation

◆ m_analysisIsOk

◆ m_detPermC

◆ m_detPermR

◆ m_diagpivotthresh

◆ m_etree

◆ m_factorizationIsOk

◆ m_glu

◆ m_info

◆ m_isInitialized

◆ m_lastError

◆ m_Lstore

◆ m_mat

◆ m_nnzL

◆ m_nnzU

◆ m_perfv

◆ m_perm_c

◆ m_perm_r

◆ m_symmetricmode

◆ m_Ustore