nmrLUSolver Class Reference
[Numerical Methods]

#include <nmrLUSolver.h>

Collaboration diagram for nmrLUSolver:

Detailed Description

Algorithm LU: LU factorization of a general M by N matrix

The class is a wrapper for the LAPACK function dgetrf. It computes an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges.

The factorization has the form $ A = P * L * U $ where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m > n), and U is upper triangular (upper trapezoidal if m < n).

The data members of this class are:

M: The number of rows of the input matrix A. M >= 0.
N: The number of columns of the input matrix A. N >= 0.
Lda: The leading dimension of the array A. $Lda \geq \mbox{max}(1,M)$ .
MinMN: Lenght of diagonal $MinMN = \mbox{min}(M,N)$
Ipiv: The pivot indices, from 1 to min(M, N).

The LAPACK function modifies the input matrix in place. The matrices L and U are stored in the same place which is pretty inconvenient to use. To reconstruct both L and U, the user can set the AllocateLU flag to true. This will allocate the correct amount of memory for L and U and the method UpdateLU will run automatically after each Solve.

Similarly, the flag AllocateP will allocate some extra memory and built the permutation matrix P based on the pivots used (IPiv).

Note:

The input matrices of this class must be column major. To select the storage order, use VCT_COL_MAJOR whenever you declare a matrix.

The input matrix must be compact (see vctDynamicMatrix::IsCompact() or vctFixedSizeMatrix::IsCompact()).

This code relies on the ERC CISST cnetlib library. Since cnetlib is optional, make sure that CISST_HAS_CNETLIB has been turned ON during the configuration with CMake.

Deprecated:: This class has been replaced by nmrLU, nmrLUDynamicData and nmrLUFixedSizeData.

Definition at line 86 of file nmrLUSolver.h.

Public Member Functions

nmrLUSolver (void)
nmrLUSolver (CISSTNETLIB_INTEGER m, CISSTNETLIB_INTEGER n, bool allocateLU=false, bool allocateP=false)
void Allocate (CISSTNETLIB_INTEGER m, CISSTNETLIB_INTEGER n, bool allocateLU=false, bool allocateP=false)
const vctDynamicVector< CISSTNETLIB_INTEGER > & GetIpiv (void) const
CISSTNETLIB_INTEGER GetInfo (void) const
const vctDynamicMatrix< CISSTNETLIB_DOUBLE > & GetP (void) const throw (std::runtime_error)
const vctDynamicMatrix< CISSTNETLIB_DOUBLE > & GetL (void) const throw (std::runtime_error)
const vctDynamicMatrix< CISSTNETLIB_DOUBLE > & GetU (void) const throw (std::runtime_error)

Allocate memory to solve this problem.

This method provides a convenient way to extract the required sizes from the input containers. The next call to the Solve() method will check that the input matches the dimension.

Parameters:

	A	The matrix to be factorized (or any matrix of the same size)
	allocateLU	Allocates memory to maintain a usable copy of L and U
	allocateP	Allocates memory to maintain a usable copy of P

void Allocate (const vctDynamicMatrix< CISSTNETLIB_DOUBLE > &A, bool allocateLU=false, bool allocateP=false)
template<vct::size_type _rows, vct::size_type _cols> void Allocate (const vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &A, bool allocateLU=false, bool allocateP=false)

template<class _matrixOwnerType> void Solve (vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &A) throw (std::runtime_error)
template<vct::size_type _rows, vct::size_type _cols> void Solve (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &A)

Protected Member Functions

void AllocateP (void)
void AllocateLU (void)
template<class _matrixOwnerType> void UpdateLU (const vctDynamicConstMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &A)
void UpdateP (void)

Protected Attributes

CISSTNETLIB_INTEGER M
CISSTNETLIB_INTEGER N
CISSTNETLIB_INTEGER Lda
CISSTNETLIB_INTEGER MinMN
CISSTNETLIB_INTEGER MaxMN
vctDynamicVector< CISSTNETLIB_INTEGER > Ipiv
CISSTNETLIB_INTEGER Info
bool AllocatePFlag
bool AllocateLUFlag
vctDynamicMatrix< CISSTNETLIB_DOUBLE > P
vctDynamicMatrix< CISSTNETLIB_DOUBLE > L
vctDynamicMatrix< CISSTNETLIB_DOUBLE > U

Constructor & Destructor Documentation

nmrLUSolver::nmrLUSolver ( void ) [inline]

Default constructor. This constructor doesn't allocate any memory. If you use this constructor, you will need to use one of the Allocate() methods before you can use the Solve method.

Definition at line 157 of file nmrLUSolver.h.

References Allocate(), AllocateLUFlag, AllocatePFlag, M, and N.

nmrLUSolver::nmrLUSolver	(	CISSTNETLIB_INTEGER	m,
		CISSTNETLIB_INTEGER	n,
		bool	allocateLU = `false`,
		bool	allocateP = `false`
	)			`[inline]`

Constructor with memory allocation. This constructor allocates the memory based on M and N. It relies on the method Allocate(). The next call to the Solve() method will check that the input matches the dimension.

Parameters:

	m	Number of rows of A
	n	Number of columns of A
	allocateLU	Allocates memory to maintain a usable copy of L and U
	allocateP	Allocates memory to maintain a usable copy of P

Definition at line 177 of file nmrLUSolver.h.

References Allocate().

Member Function Documentation

void nmrLUSolver::AllocateP ( void ) [inline, protected]

Allocates memory for the permutation matrix P.

Definition at line 103 of file nmrLUSolver.h.

References M, MaxMN, MinMN, N, P, vctDynamicMatrix< _elementType >::SetSize(), and VCT_COL_MAJOR.

Referenced by Allocate().

void nmrLUSolver::AllocateLU ( void ) [inline, protected]

Allocates memory for usable copies of L and U.

Definition at line 112 of file nmrLUSolver.h.

References vctDynamicMatrixBase< _matrixOwnerType, _elementType >::Diagonal(), L, M, MinMN, N, vctDynamicMatrixBase< _matrixOwnerType, _elementType >::SetAll(), vctDynamicMatrix< _elementType >::SetSize(), U, and VCT_COL_MAJOR.

Referenced by Allocate().

template<class _matrixOwnerType>

void nmrLUSolver::UpdateLU ( const vctDynamicConstMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > & A ) [inline, protected]

Update the content of the optional matrices L and U based on the matrix returned by the LAPACK function dgetrf.

Definition at line 124 of file nmrLUSolver.h.

References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), vctDynamicMatrixBase< _matrixOwnerType, _elementType >::Element(), L, vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows(), and U.

Referenced by Solve().

void nmrLUSolver::UpdateP ( void ) [inline, protected]

Update the content of the optional permutation matrix P based on the pivot vector IPiv.

Definition at line 141 of file nmrLUSolver.h.

References vctDynamicMatrixBase< _matrixOwnerType, _elementType >::Diagonal(), vctDynamicMatrixBase< _matrixOwnerType, _elementType >::ExchangeColumns(), Ipiv, MinMN, P, and vctDynamicMatrixBase< _matrixOwnerType, _elementType >::SetAll().

Referenced by Solve().

void nmrLUSolver::Allocate	(	CISSTNETLIB_INTEGER	m,
		CISSTNETLIB_INTEGER	n,
		bool	allocateLU = `false`,
		bool	allocateP = `false`
	)			`[inline]`

This method allocates the memory based on M and N. The next call to the Solve() method will check that the input matches the dimension.

Parameters:

	m	Number of rows of A
	n	Number of columns of A
	allocateLU	Allocates memory to maintain a usable copy of L and U
	allocateP	Allocates memory to maintain a usable copy of P

Definition at line 220 of file nmrLUSolver.h.

References AllocateLU(), AllocateLUFlag, AllocateP(), AllocatePFlag, Ipiv, Lda, M, MaxMN, MinMN, N, and vctDynamicVector< _elementType >::SetSize().

Referenced by Allocate(), and nmrLUSolver().

template<class _matrixOwnerType>

void nmrLUSolver::Solve ( vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > & A ) throw (std::runtime_error) [inline]

Performs the factorization. The result is stored in the modified input and the data member IPiv (vector of pivots).

To get a more convenient representation of the results, use turn allocateLU to true with Allocate() or the constructor. This method will then update the data members L and U (matrices). Then, one can use GetL and GetU to retrieve their content. Similarly, if one needs the complete factorization as $ P * L U $ , the matrix P can be obtained when allocateP is set with the method GetP.

Note:: This method requires a compact matrix with column major storage order. The size must match the dimension passed to the Allocate method or the constructor. An std::runtime_error exception will be thrown if these conditions are not met.

Definition at line 280 of file nmrLUSolver.h.

References AllocateLUFlag, AllocatePFlag, cmnThrow(), Info, Ipiv, Lda, M, N, vctDynamicVectorBase< _vectorOwnerType, _elementType >::Pointer(), UpdateLU(), and UpdateP().

Referenced by Solve().

template<vct::size_type _rows, vct::size_type _cols>

void nmrLUSolver::Solve ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > & A ) [inline]

Performs the factorization. The result is stored in the modified input and the data member IPiv (vector of pivots).

Note:: This method requires a compact matrix with column major storage order. The size must match the dimension passed to the Allocate method or the constructor. An std::runtime_error exception will be thrown if these conditions are not met.

Definition at line 307 of file nmrLUSolver.h.

References Solve().

const vctDynamicVector<CISSTNETLIB_INTEGER>& nmrLUSolver::GetIpiv ( void ) const [inline]

Get the vector of pivots. Since the pivots are defined in Fortran, they go from 1 to $min(M, N)$ included. To use these as C/C++ values, subtract 1.