#include <nmrLU.h>
Collaboration diagram for nmrLUDynamicData:
The result of an LU decomposition is composed of three different containers, the matrices P, L and U defined by 
. 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:
Definition at line 85 of file nmrLU.h.
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.
| 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.
Definition at line 329 of file nmrLU.h.
References AllocateOutput().
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.
| m,n | Dimension of the matrix to be decomposed. |
Definition at line 345 of file nmrLU.h.
References Allocate().
| 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.
| A | input matrix |
Definition at line 360 of file nmrLU.h.
References Allocate().
| 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.
| A | The matrix to be decomposed, used to verify the sizes. | |
| pivotIndices | Vector created by the user to store the output. |
Definition at line 378 of file nmrLU.h.
References SetRef().
| void nmrLUDynamicData::AllocateOutput | ( | bool | allocateOutput | ) | [inline, protected] |
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).
Definition at line 135 of file nmrLU.h.
References MMember, NMember, OutputMemory, PivotIndicesReference, vctDynamicVectorRef< _elementType >::SetRef(), and vctDynamicVector< _elementType >::SetSize().
Referenced by Allocate(), nmrLUDynamicData(), and SetRef().
| void nmrLUDynamicData::ThrowUnlessOutputSizeIsCorrect | ( | vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > & | pivotIndices | ) | throw (std::runtime_error) [inline, protected] |
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.
Definition at line 155 of file nmrLU.h.
References cmnThrow(), MMember, and NMember.
Referenced by SetRef().
| static nsize_type nmrLUDynamicData::MatrixPSize | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A | ) | [inline, static] |
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.
| A | The matrix to be decomposed using nmrLU (it is used only to determine the sizes). |
Definition at line 180 of file nmrLU.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows().
| static nsize_type nmrLUDynamicData::MatrixLSize | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A | ) | [inline, static] |
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.
| A | The matrix to be decomposed using nmrLU (it is used only to determine the sizes). |
Definition at line 195 of file nmrLU.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), and vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows().
| static nsize_type nmrLUDynamicData::MatrixUSize | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A | ) | [inline, static] |
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.
| A | The matrix to be decomposed using nmrLU (it is used only to determine the sizes). |
Definition at line 211 of file nmrLU.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), and vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows().
| 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) [inline, static] |
Helper method to create a usable permutation matrix from the vector of pivot indices created by nmrLU.
| 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. |
Definition at line 230 of file nmrLU.h.
References cmnThrow().
| static void nmrLUDynamicData::UpdateMatrixLU | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A, | |
| vctDynamicMatrixBase< _matrixOwnerTypeL, CISSTNETLIB_DOUBLE > & | L, | |||
| vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > & | U | |||
| ) | throw (std::runtime_error) [inline, static] |
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.
| A | The matrix decomposed using nmrLU. | |
| L | The lower matrix | |
| U | The upper matrix |
| 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.
| A | The matrix for which LU needs to be computed, size MxN |
Definition at line 394 of file nmrLU.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), and vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows().
Referenced by nmrLUDynamicData().
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.
| m | Number of rows of input matrix A. | |
| n | Number of cols of input matrix A. |
Definition at line 406 of file nmrLU.h.
References AllocateOutput(), and SetDimension().
| 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.
| A | The matrix to be decomposed, used to verify the sizes. | |
| pivotIndices | Vector created by the user to store the output. |
Definition at line 425 of file nmrLU.h.
References AllocateOutput(), PivotIndicesReference, SetDimension(), vctDynamicVectorRef< _elementType >::SetRef(), and ThrowUnlessOutputSizeIsCorrect().
Referenced by nmrLUDynamicData().
| 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.
Definition at line 438 of file nmrLU.h.
References PivotIndicesReference.
vctDynamicVector<CISSTNETLIB_INTEGER> nmrLUDynamicData::OutputMemory [protected] |
Memory allocated for pivot indices vector if needed.
Definition at line 99 of file nmrLU.h.
Referenced by AllocateOutput().
vctDynamicVectorRef<CISSTNETLIB_INTEGER> nmrLUDynamicData::PivotIndicesReference [protected] |
Reference return type, this points either to user allocated memory or our memory chunk if needed.
Definition at line 104 of file nmrLU.h.
Referenced by AllocateOutput(), PivotIndices(), and SetRef().
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.
Definition at line 109 of file nmrLU.h.
Referenced by AllocateOutput(), SetDimension(), and ThrowUnlessOutputSizeIsCorrect().
size_type nmrLUDynamicData::NMember [protected] |
Just store M, and N which are needed to check if A matrix passed to solve method matches the allocated size.
Definition at line 110 of file nmrLU.h.
Referenced by AllocateOutput(), SetDimension(), and ThrowUnlessOutputSizeIsCorrect().