Data of LU problem (Dynamic). More...

#include <nmrLU.h>

Classes
class	Friend

Public Types
typedef vct::size_type	size_type

typedef vctFixedSizeVector < size_type, 2 >	nsize_type

Public Member Functions
	nmrLUDynamicData ()

	nmrLUDynamicData (size_type m, size_type n)

template<class _matrixOwnerTypeA >
	nmrLUDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >
	nmrLUDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices)

template<class _matrixOwnerTypeA >
void	Allocate (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

void	Allocate (size_type m, size_type n)

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >
void	SetRef (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices) throw (std::runtime_error)

const vctDynamicVectorRef < CISSTNETLIB_INTEGER > &	PivotIndices (void) const

Static Public Member Functions
template<class _matrixOwnerTypeA >
static nsize_type	MatrixPSize (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

template<class _matrixOwnerTypeA >
static nsize_type	MatrixLSize (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

template<class _matrixOwnerTypeA >
static nsize_type	MatrixUSize (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices , class _matrixOwnerTypeP >
static vctDynamicMatrixBase < _matrixOwnerTypeP, CISSTNETLIB_DOUBLE > &	UpdateMatrixP (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, const vctDynamicConstVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices, vctDynamicMatrixBase< _matrixOwnerTypeP, CISSTNETLIB_DOUBLE > &P) throw (std::runtime_error)

template<class _matrixOwnerTypeA , class _matrixOwnerTypeL , class _matrixOwnerTypeU >
static void	UpdateMatrixLU (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicMatrixBase< _matrixOwnerTypeL, CISSTNETLIB_DOUBLE > &L, vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &U) throw (std::runtime_error)

Protected Member Functions
void	SetDimension (size_type m, size_type n)

void	AllocateOutput (bool allocateOutput)

template<class _vectorOwnerTypePivotIndices >
void	ThrowUnlessOutputSizeIsCorrect (vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices) throw (std::runtime_error)

Protected Attributes
vctDynamicVector < CISSTNETLIB_INTEGER >	OutputMemory

vctDynamicVectorRef < CISSTNETLIB_INTEGER >	PivotIndicesReference


size_type	MMember

size_type	NMember

Friends
class	Friend

Detailed Description

Data of LU problem (Dynamic).

The result of an LU decomposition is composed of three different containers, the matrices P, L and U defined by $ A = P * L * U$ . The sizes of these components must match exactly the input matrix A. To ease the use of the LU routine, the user can rely on the nmrLUDynamicData class to perform the required memory allocation.

Another good reason to use a data object is that the memory allocation can be performed once during an initialization phase while the function nmrLU can be called numerous times later on without any new dynamic memory allocation. This is crucial for such things as real time tasks.

The LU routine, as most LAPACK and FORTRAN based routines, requires the input to be stored column first. In cisstVector, this implies that all matrices must be created using VCT_COL_MAJOR. Furthermore, all matrices and vectors must also be compact, i.e. use a contiguous block of memory.

Any size or storage order mismatch will lead to an exception thrown (std::runtime_error). Since we are using cmnThrow, it is possible to configure cisst (at compilation time) to abort the program instead of throwing an exception.

The nmrLUDynamicData class allows 2 different configurations:

Allocate automatically the output (PivotIndices vector). This can be performed using either the constructor from input matrix (i.e. nmrLUDynamicData(A)) or using the method Allocate(A).
Don't allocate anything. The user has to provide the container he wants to use for the pivot indices. In this case, the data is used mostly to check that the container is valid in terms of size. This can be performed using either the constructor from PivotIndices (i.e. nmrSVDDynamicData(A, PivotIndices)) or the method SetRef(A, PivotIndices).

See Also: nmrLU

Member Typedef Documentation

typedef vctFixedSizeVector<size_type, 2> nmrLUDynamicData::nsize_type

typedef vct::size_type nmrLUDynamicData::size_type

Type used for sizes within nmrLUDynamicData. This type is compatible with the cisstVector containers such as vctDynamicMatrix and vctDynamicVector (unsigned int). To call the Fortran based routines, these values must be cast to #CISSTNETLIB_INTEGER.

Constructor & Destructor Documentation

nmrLUDynamicData::nmrLUDynamicData ( )

inline

The default constuctor. For dynamic size, there are assigned default values, i.e. sets all the dimensions to zero. These MUST be changed by calling the appropriate method.

See Also: nmrLUDynamicData::Allocate nmrLUDynamicData::SetRef

nmrLUDynamicData::nmrLUDynamicData	(	size_type	m,
		size_type	n
	)

inline

Constructor where the user specifies the size. Memory allocation is performed for pivot indices vector. This should be used when the user doesn't care much about where the output should be stored.

Parameters

m,n	Dimension of the matrix to be decomposed.

See Also: nmrLUDynamicData::Allocate

template<class _matrixOwnerTypeA >

nmrLUDynamicData::nmrLUDynamicData ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inline

Constructor where the user provides the input matrix to specify the size and storage order. Memory allocation is performed for pivot indices vector. This should be used when the user doesn't care much about where the output should be stored.

Parameters

A	input matrix

See Also: nmrLUDynamicData::Allocate

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >

nmrLUDynamicData::nmrLUDynamicData	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &	pivotIndices
	)

inline

Constructor where the user provides the vector to store the pivot indices. The data object now acts as a composite container to hold, pass and manipulate a convenient storage for LU algorithm. Checks are made on the validity of the input and its consitency in terms of size.

Parameters

A	The matrix to be decomposed, used to verify the sizes.
pivotIndices	Vector created by the user to store the output.

See Also: nmrLUDynamicData::SetRef

Member Function Documentation

template<class _matrixOwnerTypeA >

void nmrLUDynamicData::Allocate ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inline

This method allocates memory for the output vector (pivot indices). The input matrix is used only to determine the size of the problem.

This method should be called before the nmrLUDynamicData object is passed on to nmrLU function.

Parameters

A	The matrix for which LU needs to be computed, size MxN

void nmrLUDynamicData::Allocate	(	size_type	m,
		size_type	n
	)

inline

This method allocates the memory for the output (pivot indices). This method is not meant to be a top-level user API, but is used by other overloaded Allocate methods.

Parameters

m	Number of rows of input matrix A.
n	Number of cols of input matrix A.

void nmrLUDynamicData::AllocateOutput ( bool allocateOutput )

inlineprotected

Private method to allocate memory for the output if needed. This method assumes that the dimension m and n as well as the storage order are already set. It is important to use this method in all the methods provided in the user API, even if all the memory is provided by the user since this method will ensure that the data (nmrLUDynamicData) does not keep any memory allocated. This is for the case where a single data object is used first to allocate everything and, later on, used with user allocated memory (for the output).

Note: The method SetDimension must have been called before.

template<class _matrixOwnerTypeA >

static nsize_type nmrLUDynamicData::MatrixLSize ( const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inlinestatic

Helper method to compute the size of the matrix L. This method can be used before UpdateMatrixLU to make sure that the size of L is correct.

Parameters

A	The matrix to be decomposed using nmrLU (it is used only to determine the sizes).

template<class _matrixOwnerTypeA >

static nsize_type nmrLUDynamicData::MatrixPSize ( const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inlinestatic

Helper method to compute the size of the permutation matrix. This method can be used before UpdateMatrixP to make sure that the size of P is correct.

Parameters

A	The matrix to be decomposed using nmrLU (it is used only to determine the sizes).

template<class _matrixOwnerTypeA >

static nsize_type nmrLUDynamicData::MatrixUSize ( const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inlinestatic

Helper method to compute the size of the matrix U. This method can be used before UpdateMatrixLU to make sure that the size of U is correct.

Parameters

A	The matrix to be decomposed using nmrLU (it is used only to determine the sizes).

const vctDynamicVectorRef<CISSTNETLIB_INTEGER>& nmrLUDynamicData::PivotIndices ( void ) const

inline

Const reference to the result vector PivotIndices. This method must be called after the data has been computed by the nmrLU function.

void nmrLUDynamicData::SetDimension	(	size_type	m,
		size_type	n
	)

inlineprotected

Private method to set the data members MMember and NMember. This method must be called before AllocateOutput, ThrowUnlessOutputSizeIsCorrect or ThrowUnlessWorkspaceSizeIsCorrect.

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >

void nmrLUDynamicData::SetRef	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &	pivotIndices
	)
throw	(	std::runtime_error
	)

inline

This method doesn't allocate any memory as it relies on the user provided vector (pivotIndices).

The data object now acts as a composite container to hold, pass and manipulate a convenient storage for LU algorithm. The method tests that all the containers provided by the user have the correct size and are compact.

Parameters

A	The matrix to be decomposed, used to verify the sizes.
pivotIndices	Vector created by the user to store the output.

template<class _vectorOwnerTypePivotIndices >

void nmrLUDynamicData::ThrowUnlessOutputSizeIsCorrect	(	vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &	pivotIndices	)
throw	(	std::runtime_error
	)

inlineprotected

Verifies that the user provided references for the output match the size of the data object as set by SetDimension. This method also checks that all containers are compact.

Note: The method SetDimension must have been called before.

template<class _matrixOwnerTypeA , class _matrixOwnerTypeL , class _matrixOwnerTypeU >

static void nmrLUDynamicData::UpdateMatrixLU	(	const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		vctDynamicMatrixBase< _matrixOwnerTypeL, CISSTNETLIB_DOUBLE > &	L,
		vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &	U
	)
throw	(	std::runtime_error
	)

inlinestatic

Helper method to create usable matrix L and U from the input matrix used and modified by nmrLU. The output of nmrLU is a single matrix which contains both L and U. This method splits the output of nmrLU and creates to matrices by copying the lower and upper parts respectively in L and U, setting all other elements to zero. The diagonal of the output is copied to U while all the elements of the diagonal of L are set to 1.

Note: This method must be called after the nmrLU function has been called.

Parameters

A	The matrix decomposed using nmrLU.
L	The lower matrix
U	The upper matrix

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices , class _matrixOwnerTypeP >

static vctDynamicMatrixBase<_matrixOwnerTypeP, CISSTNETLIB_DOUBLE>& nmrLUDynamicData::UpdateMatrixP	(	const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		const vctDynamicConstVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &	pivotIndices,
		vctDynamicMatrixBase< _matrixOwnerTypeP, CISSTNETLIB_DOUBLE > &	P
	)
throw	(	std::runtime_error
	)

inlinestatic

Helper method to create a usable permutation matrix from the vector of pivot indices created by nmrLU.

Note: This method must be called after the nmrLU function has been called.

Parameters

A	The matrix decomposed using nmrLU. It is used only to check the sizes.
pivotIndices	The vector of pivot indices as computed by nmrLU
P	The permutation matrix updated from the pivot indices.

Friends And Related Function Documentation

friend class Friend

friend

Member Data Documentation

size_type nmrLUDynamicData::MMember

protected

Just store M, and N which are needed to check if A matrix passed to solve method matches the allocated size.

size_type nmrLUDynamicData::NMember

protected

vctDynamicVector<CISSTNETLIB_INTEGER> nmrLUDynamicData::OutputMemory

protected

Memory allocated for pivot indices vector if needed.

vctDynamicVectorRef<CISSTNETLIB_INTEGER> nmrLUDynamicData::PivotIndicesReference

protected

Reference return type, this points either to user allocated memory or our memory chunk if needed.

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

/home/adeguet1/catkin_ws/src/cisst-saw/cisst/cisstNumerical/nmrLU.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation