nmrInverse.h File Reference

Declaration of nmrInverse. More...

#include <cisstCommon/cmnThrow.h>
#include <cisstVector/vctFixedSizeMatrix.h>
#include <cisstVector/vctDynamicMatrix.h>
#include <cisstNumerical/nmrNetlib.h>
#include <cisstNumerical/nmrExport.h>

Go to the source code of this file.

Classes
class	nmrInverseDynamicData
	Data for Inverse problem (Dynamic). More...
class	nmrInverseDynamicData::Friend
class	nmrInverseFixedSizeData< _size, _storageOrder >
	Data for Inverse problem (Fixed size). More...
class	nmrInverseFixedSizeData< _size, _storageOrder >::Friend

Functions
Algorithm Inverse: Compute the inverse of a square matrix
using Lower Upper Decomposition These functions are different wrappers for the LAPACK function dgetrf and dgetri. They compute the inverse factorization of a square matrix A. These functions are wrappers around the LAPACK routine dgetrf and dgetri, therefore they share some features with the LAPACK routine: On exit, the content of A is altered. The vectors and matrices must be compact, i.e. use a contiguous block of memory. The nmrInverse functions add the following features: A simplified interface to the cisstVector matrices, either vctDynamicMatrix or vctFixedSizeMatrix. Input validation checks are performed, i.e. an std::runtime_error exception will be thrown if the sizes or storage order don't match or if the containers are not compact. Helper classes to allocate memory for the output and workspace: nmrInverseFixedSizeData and nmrInverseDynamicData. There are different ways to call this function to compute the Inverse of the matrix A. These correspond to different overloaded nmrInverse functions: Using a preallocated data object. The user creates the input matrix A: vctDynamicMatrix<CISSTNETLIB_DOUBLE> A(12, 24 , VCT_COL_MAJOR); // 12 x 24 matrix vctRandom(A, -10.0, 10.0); The user allocates a data object which could be of type nmrInverseFixedSizeData or nmrInverseDynamicData. corresponding to fixed size or dynamic matrix A: nmrInverseDynamicData data(A); Call the nmrInverse function: nmrInverse(A, data); The content of input matrix A is modified by this routine. The user provides the vector pivotIndices and workspace. The User allocates memory for this vector: vctDynamicMatrix<CISSTNETLIB_DOUBLE> A(5, 5, VCT_COL_MAJOR); vctRandom(A, -10.0, 10.0); vctDynamicVector<CISSTNETLIB_INTEGER> pivotIndices(nmrInverseDynamicData::PivotIndicesSize(A)); vctDynamicVector<CISSTNETLIB_DOUBLE> workspace(nmrInverseDynamicData::WorkspaceSize(A)); Call the Inverse routine: nmrInverse(A, pivotIndices, workspace); The Inverse function verifies that the size of the data objects matches the input. Using a data for fixed size containers. vctFixedSizeMatrix<CISSTNETLIB_DOUBLE, 5, 5, VCT_COL_MAJOR> A; vctRandom(A, -10.0, 10.0); typedef nmrInverseFixedSizeData<5, VCT_COL_MAJOR> DataType; DataType data; nmrInverse(A, data); Note The Inverse functions make use of LAPACK routines. To activate this code, set the CISST_HAS_CISSTNETLIB flag to ON during the configuration of cisst with CMake.
template<class _matrixOwnerType >
CISSTNETLIB_INTEGER	nmrInverse (vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &A, nmrInverseDynamicData &data) throw (std::runtime_error)
template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices , class _vectorOwnerTypeWorkspace >
CISSTNETLIB_INTEGER	nmrInverse (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)
template<class _matrixOwnerTypeA >
CISSTNETLIB_INTEGER	nmrInverse (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)
template<vct::size_type _size, vct::size_type _maxSize1, vct::size_type _lWork, bool _storageOrder>
CISSTNETLIB_INTEGER	nmrInverse (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &A, vctFixedSizeVector< CISSTNETLIB_INTEGER, _maxSize1 > &pivotIndices, vctFixedSizeVector< CISSTNETLIB_DOUBLE, _lWork > &workspace)
template<vct::size_type _size, bool _storageOrder>
CISSTNETLIB_INTEGER	nmrInverse (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &A, nmrInverseFixedSizeData< _size, _storageOrder > &data)
template<vct::size_type _size, bool _storageOrder>
CISSTNETLIB_INTEGER	nmrInverse (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &A)

Detailed Description

Declaration of nmrInverse.

Function Documentation

template<class _matrixOwnerType >

CISSTNETLIB_INTEGER nmrInverse ( vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &  A, nmrInverseDynamicData &  data  ) throw ( std::runtime_error )

inline

This function solves the Inverse problem for a dynamic matrix using an nmrInverseDynamicData.

This function checks for valid input (size and compact) and calls the LAPACK function. If the input doesn't match the data, an exception is thrown (std::runtime_error).

This function modifies the input matrix A and stores the results in the data.

Parameters

A	A square matrix, either vctDynamicMatrix or vctDynamicMatrixRef.
data	A data object corresponding to the input matrix.

Test:

nmrInverseTest::TestDynamicColumnMajor nmrInverseTest::TestDynamicRowMajor

template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices , class _vectorOwnerTypeWorkspace >

CISSTNETLIB_INTEGER nmrInverse ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A, vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &  pivotIndices, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  workspace  )

inline

This function solves the Inverse problem for a dynamic matrix using the storage provided by the user (pivotIndices and workspace).

Internally, a data is created using the storage provided by the user (see nmrInverseDynamicData::SetRef). While the data is being build, the consistency of the output is checked. Then, the nmrInverse(A, data) function can be used safely.

Parameters

A	is a reference to a dynamic square matrix
pivotIndices	Vector created by the user to store the pivot indices.
workspace	Vector created by the user for the workspace.

Test:

nmrInverseTest::TestDynamicColumnMajorUserAlloc nmrInverseTest::TestDynamicRowMajorUserAlloc

template<class _matrixOwnerTypeA >

CISSTNETLIB_INTEGER nmrInverse ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A )

inline

This function solves the Inverse problem for a dynamic matrix.

Internally, a data object is created. This forces the dynamic allocation of the pivot indices vector as well as the workspace vector. Then, the nmrInverse(A, data) function can be used safely.

Parameters

A	is a reference to a dynamic square matrix

template<vct::size_type _size, vct::size_type _maxSize1, vct::size_type _lWork, bool _storageOrder>

CISSTNETLIB_INTEGER nmrInverse ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &  A, vctFixedSizeVector< CISSTNETLIB_INTEGER, _maxSize1 > &  pivotIndices, vctFixedSizeVector< CISSTNETLIB_DOUBLE, _lWork > &  workspace  )

inline

This function solves the Inverse problem for a fixed size matrix using the storage provided by the user for the pivot indices vector as well as the workspace vector.

The sizes of the matrices must match at compilation time. This is enforced by the template parameters and matching problems will lead to compilation errors. Since there is no easy way to enforce the size of the vector pivotIndices with template parameters, a runtime check is performed. The test uses CMN_ASSERT to determine what to do if the sizes don't match. By default CMN_ASSERT calls abort() but it can be configured to be ignored or to throw an exception (see CMN_ASSERT for details).

This function modifies the input matrix A.

Parameters

A	is a fixed size square matrix.
pivotIndices	Vector created by the caller for the pivot indices.
workspace	Vector created by the caller for the workspace.

Test:

TestFixedSizeColumnMajorUserAlloc TestFixedSizeRowMajorUserAlloc

template<vct::size_type _size, bool _storageOrder>

CISSTNETLIB_INTEGER nmrInverse ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &  A, nmrInverseFixedSizeData< _size, _storageOrder > &  data  )

inline

This function solves the Inverse problem for a fixed size matrix using nmrInverseFixedSizeData to allocate the memory required for the pivot indices and the workspace:

vctFixedSizeMatrix<CISSTNETLIB_DOUBLE, 7, 7, VCT_ROW_MAJOR> A;
vctRandom(A, -10.0, 10.0);
nmrInverseFixedSizeData<7, VCT_ROW_MAJOR> data;
nmrInverse(A, data);

This method calls nmrInverse(A, pivotIndices, workspace).

Parameters

A	A fixed size square matrix.
data	A data object.

Test:

TestFixedSizeColumnMajor TestFixedSizeRowMajor

template<vct::size_type _size, bool _storageOrder>

CISSTNETLIB_INTEGER nmrInverse ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _size, _size, _storageOrder > &  A )

inline

This function solves the Inverse problem for a fixed size matrix.

Internally, a data object is created. This forces the allocation (stack) of the pivot indices vector as well as the workspace vector. Then, the nmrInverse(A, data) function can be used safely.

Parameters

A	A fixed size square matrix.