#include <nmrPInverseEconomy.h>

Classes
class	Friend

Public Types
typedef unsigned int	size_type

Public Member Functions
	nmrPInverseEconomyDynamicData ()

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

template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >
	nmrPInverseEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)

template<class _matrixOwnerTypeA , class _matrixOwnerTypePInverse , class _vectorOwnerTypeWorkspace >
	nmrPInverseEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &CMN_UNUSED(A), vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &pInverse, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)

template<class _matrixOwnerTypeA , class _matrixOwnerTypePInverse >
	nmrPInverseEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &CMN_UNUSED(A), vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &pInverse)

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

template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >
void	SetRefWorkspace (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)

template<class _matrixOwnerTypePInverse , class _vectorOwnerTypeWorkspace >
void	SetRef (vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &pInverse, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)

template<class _matrixOwnerTypePInverse >
void	SetRefOutput (vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &pInverse)

Retrieving results.
In order to get access to U, V^t and S, after the have been computed by calling nmrPInverseEconomy, use the following methods.
const vctDynamicVectorRef < CISSTNETLIB_DOUBLE > &	S (void) const

const vctDynamicMatrixRef < CISSTNETLIB_DOUBLE > &	U (void) const

const vctDynamicMatrixRef < CISSTNETLIB_DOUBLE > &	Vt (void) const

const vctDynamicMatrixRef < CISSTNETLIB_DOUBLE > &	PInverse (void) const

Static Public Member Functions
static size_type	WorkspaceSize (size_type m, size_type n)

template<class _matrixOwnerTypeA >
static size_type	WorkspaceSize (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)

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

void	AllocateOutputWorkspace (bool allocateOutput, bool allocateWorkspace)

template<class _vectorOwnerTypeWorkspace >
void	SetRefSVD (vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace)

template<typename _matrixOwnerTypePInverse >
void	ThrowUnlessOutputSizeIsCorrect (vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &pInverse) const throw (std::runtime_error)

template<typename _vectorOwnerTypeWorkspace >
void	ThrowUnlessWorkspaceSizeIsCorrect (vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &workspace) const throw (std::runtime_error)

Protected Attributes
vctDynamicVector < CISSTNETLIB_DOUBLE >	WorkspaceMemory

vctDynamicVector < CISSTNETLIB_DOUBLE >	OutputMemory

size_type	MMember

size_type	NMember

bool	StorageOrderMember


vctDynamicMatrixRef < CISSTNETLIB_DOUBLE >	PInverseReference

vctDynamicMatrixRef < CISSTNETLIB_DOUBLE >	UReference

vctDynamicMatrixRef < CISSTNETLIB_DOUBLE >	VtReference

vctDynamicVectorRef < CISSTNETLIB_DOUBLE >	SReference

vctDynamicVectorRef < CISSTNETLIB_DOUBLE >	WorkspaceReference

Friends
class	Friend

Detailed Description

Algorithm P-Inverse: Moore-Penrose pseudo-inverse Calculates the Moore-Penrose pseudo-inverse of the M by N matrix A, and stores the result in PInverse. The singular values of A are returned in S. The left singular vectors are returned in U, and the right singular vectors are returned in V.

$A^{+} = V * \Sigma^{+} * U^{T}$

where $\Sigma^{+}$ is a $N \times M$ matrix which is zero except for its min(m,n) diagonal elements, U is a $M \times M$ orthogonal matrix, and V is a $N \times N$ orthogonal matrix. The diagonal elements of $\Sigma^{+}$ are the reciprocal ofc non-zero singular values of A; they are real and non-negative, andc are returned in descending order. The first $\mbox{min}(m,n)$ columns of U and V are the left and right singular vectors of A.

Note: This routine returns $V^{T}$ , not .; On exit, the content of A is altered.

There are three ways to call this method to compute the pseudo-inverse of the matrix A. METHOD 1: User provides matrices A and A^{+} 1) The User allocates memory for these matrices and vector. vctDynamicMatrix<CISSTNETLIB_DOUBLE> A(5, 4); vctDynamicMatrix<CISSTNETLIB_DOUBLE> PInverse(4, 5); ... 2) The user calls the SVD routine nmrPInverseEconomy(A, PInverse); The PInverse method verifies that the size of the data objects matches the input, and allocates workspace memory, which is deallocated when the function ends. The PInverse function alters the contents of matrix A. For fixed size the function call is templated by size and row/column major, e.g. nmrPInverseEconomy<4, 3, VCT_COL_MAJOR>(A, PInverse);

METHOD 2: Using a preallocated data object 1) The user creates the input matrix vctDynamicMatrix<CISSTNETLIB_DOUBLE> input(rows, cols , VCT_ROW_MAJOR); 2) The user allocats a data object which could be of type nmrPInverseEconomyDynamicData and nmrPInverseEconomyDynamicDataRef corresponding to fixed size, dynamic matrix or dynamic matrix reference. nmrPInverseEconomyDynamicData data(input); 3) Call the nmrPInverseEconomy function nmrPInverseEconomy(input, data); The contents of input matrix is modified by this routine. The matrices U, Vt and vector S are available through the following methods std::cout << data.U() << data.S() << data.Vt() << std::endl; The pseudo-inverse is available through data.PInverse()

METHOD 3: User provides matrix PInverse with workspace required by pseudo-inverse routine of LAPACK. 1) User creates matrices and vector vctDynamicMatrix<CISSTNETLIB_DOUBLE> A(5, 4); vctDynamicMatrix<CISSTNETLIB_DOUBLE> PInverse(4, 5); 2) User also needs to allocate memory for workspace. This method is particularly useful when the user is using more than one numerical methods from the library and is willing to share the workspace between them. In such as case, the user can allocate the a memory greater than the maximum required by different methods. To aid the user determine the minimum workspace required (and not spend time digging LAPACK documentation) the library provides helper function nmrPInverseEconomyDynamicData::WorkspaceSize(input) vctDynamicVector<CISSTNETLIB_DOUBLE> Work(nmrPInverseEconomyDynamicData::WorkspaceSize(A)); 3) Call the SVD function nmrPInverseEconomy(A, PInverse, Work);

Note: The PInverse functions make use of LAPACK routines. To activate this code, set the CISST_HAS_CISSTNETLIB flag to ON during the configuration with CMake.; The general rule for numerical functions which depend on LAPACK is that column-major matrices should be used everywhere, and that all matrices should be compact.; For the specific case of PInverse, a valid result is also obtained if all the matrices are stored in row-major order. This is an exeption to the general rule. However, mixed-order is not tolerated.

This is the class for the composite data container of PInverse.

Member Typedef Documentation

typedef unsigned int nmrPInverseEconomyDynamicData::size_type

Type used for sizes within nmrSVDEconomyDynamicData. 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

nmrPInverseEconomyDynamicData::nmrPInverseEconomyDynamicData ( )

inline

The default constuctor. For dynamic size, there are assigned default values, which MUST be changed by calling appropriate methods. (See nmrPInverseEconomyDynamicData::Allocate and nmrPInverseEconomyDynamicData::SetRef)

template<class _matrixOwnerTypeA >

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

inline

Constructor where user provides the input matrix to specify size, Memory allocation is done for output matrices and vectors as well as Workspace used by LAPACK. This case covers the scenario when user wants to make all system calls for memory allocation before entrying time critical code sections.

Parameters

A	Input matrix

template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >

nmrPInverseEconomyDynamicData::nmrPInverseEconomyDynamicData	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &	workspace
	)

inline

Constructor where user provides the input matrix to specify size, Memory allocation is done for output matrices and vectors. This case covers the scenario when user wants to make all system calls for memory allocation before entrying time critical code sections and might be using more than one numerical method in the same thread, allowing her to share the workspace for LAPACK.

Parameters

A	Input matrix
workspace	Workspace for SVD

template<class _matrixOwnerTypeA , class _matrixOwnerTypePInverse , class _vectorOwnerTypeWorkspace >

nmrPInverseEconomyDynamicData::nmrPInverseEconomyDynamicData	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	CMN_UNUSEDA,
		vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &	pInverse,
		vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &	workspace
	)

inline

Constructor where user provides the size and storage order of the input matrix, along with matrix AP and workspace. The data object now acts as a composite container to hold, pass and manipulate a convenitent storage for PInverse algorithm. Checks are made on the validity of the input and its consitency with the size of input matrix.

Parameters

A	The input matrix
pInverse	The output matrices for PInverse
workspace	The workspace for LAPACK.

template<class _matrixOwnerTypeA , class _matrixOwnerTypePInverse >

nmrPInverseEconomyDynamicData::nmrPInverseEconomyDynamicData	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	CMN_UNUSEDA,
		vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &	pInverse
	)

inline

Constructor where user provides the size and storage order of the input matrix, along with matrix PInverse. The data object now acts as a composite container to hold, pass and manipulate a convenitent storage for SVD algorithm. Checks are made on thec validity of the input and its consitency with the size of input matrix. Memory allocation for workspace is done by the method. This case covers the scenario when user wants to make all system calls for memory allocation before entrying time critical code sections and might be using the PInverse matrix elsewhere in the same* thread.

Parameters

A	Input matrix
pInverse	The output matrix for PInverse

Member Function Documentation

template<class _matrixOwnerTypeA >

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

inline

This method allocates memory of output matrices and vector as well as the workspace. This method should be called before the nmrPInverseEconomyDynamicData object is passed on to nmrPInverseEconomy function, as the memory required for output matrices and workspace are allocated here or to reallocate memory previously allocated by constructor. Typically this method is called from a code segment where it is safe to allocate memory and use the data and workspace space later.

Parameters

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

void nmrPInverseEconomyDynamicData::AllocateOutputWorkspace	(	bool	allocateOutput,
		bool	allocateWorkspace
	)

inlineprotected

Private method to allocate memory for the output and the workspace 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 (nmrPInverseEconomyDynamicData) does not keep any memory allocated. This is for the case where a single data is used first to allocate everything and, later on, used with user allocated memory (for either the workspace or the output).

Note: The method SetDimension must have been called before.

const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrPInverseEconomyDynamicData::PInverse ( void ) const

inline

const vctDynamicVectorRef<CISSTNETLIB_DOUBLE>& nmrPInverseEconomyDynamicData::S ( void ) const

inline

void nmrPInverseEconomyDynamicData::SetDimension	(	size_type	m,
		size_type	n,
		bool	storageOrder
	)

inlineprotected

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

template<class _matrixOwnerTypePInverse , class _vectorOwnerTypeWorkspace >

void nmrPInverseEconomyDynamicData::SetRef	(	vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &	pInverse,
		vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &	workspace
	)

inline

This method must be called before the data object is passed to nmrPInverseEconomy function. The user provides the PInverse matrix to specify size, along with the workspace. The data object now acts as a composite container to hold, pass and manipulate a convenitent storage for PInverse algorithm. Checks are made on the validity of the input and its consitency with the size of input matrix.

Parameters

pInverse	The output matrix for PInverse
workspace	The workspace for LAPACK.

template<class _matrixOwnerTypePInverse >

void nmrPInverseEconomyDynamicData::SetRefOutput ( vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > & pInverse )

inline

This method must be called before the data object is passed to nmrPInverseEconomy function. The user provides the PInverse matrix to specify size. The data object now acts as a composite container to hold, pass and manipulate a convenitent storage for PInverse algorithm. Checks are made on thec validity of the input and its consitency with the size of input matrix. Memory allocation for workspace is done by the method. This case covers the scenario when user wants to make all system calls for memory allocation before entrying time critical code sections and might be using the PInverse matrix elsewhere in the same thread.

Parameters

pInverse The output matrix for PInverse

template<class _vectorOwnerTypeWorkspace >

void nmrPInverseEconomyDynamicData::SetRefSVD ( vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > & workspace )

inlineprotected

Set all internal references used for the SVD problem. This method requires a valid workspace but it doesn't check the size. It is the caller responsability to do so.

Note: The method SetDimension must have been called before.

template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >

void nmrPInverseEconomyDynamicData::SetRefWorkspace	(	vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &	A,
		vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &	workspace
	)

inline

This method allocates memory of output matrices and vector and uses the memory provided by user for workspace. Check is made to ensure that memory provided by user is sufficient for SVD routine of LAPACK. This method should be called before the nmrPInverseEconomyDynamicData object is passed on to nmrPInverseEconomy function, as the memory required for output matrices and workspace are allocated here or to reallocate memory previously allocated by constructor. This case covers the scenario when user wants to make all system calls for memory allocation before entrying time critical code sections and might be using more than one numerical method in the same thread, allowing her to share the workspace for LAPACK. Typically this method is called from a code segment where it is safe to allocate memory and use the data and workspace space later.

Parameters

A	The matrix for which SVD needs to be computed, size MxN
workspace	The vector used for workspace by LAPACK.

template<typename _matrixOwnerTypePInverse >

void nmrPInverseEconomyDynamicData::ThrowUnlessOutputSizeIsCorrect	(	vctDynamicMatrixBase< _matrixOwnerTypePInverse, CISSTNETLIB_DOUBLE > &	pInverse	)	const
throw	(	std::runtime_error
	)

inlineprotected

Verifies that the user provided reference for the output match the size of the data as set by SetDimension. This method also checks that the storage order is consistent.

Note: The method SetDimension must have been called before.

template<typename _vectorOwnerTypeWorkspace >

void nmrPInverseEconomyDynamicData::ThrowUnlessWorkspaceSizeIsCorrect	(	vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &	workspace	)	const
throw	(	std::runtime_error
	)

inlineprotected

Verifies that the user provided references for the workspace match (or is greated than) the size of the data as set by SetDimension. This method also checks that the workspace is compact.

Note: The method SetDimension must have been called before.

const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrPInverseEconomyDynamicData::U ( void ) const

inline

const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrPInverseEconomyDynamicData::Vt ( void ) const

inline

static size_type nmrPInverseEconomyDynamicData::WorkspaceSize	(	size_type	m,
		size_type	n
	)

inlinestatic

Helper methods for user to set min working space required by LAPACK SVD routine plus memory needed for S, U & Vt matrices used to compute PInverse.

Parameters

m,n	The size of matrix whose SVD needs to be computed

template<class _matrixOwnerTypeA >

static size_type nmrPInverseEconomyDynamicData::WorkspaceSize ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & A )

inlinestatic

Helper method to determine the min working space required by LAPACK SVD routine plus memory needed for S, U & Vt matrices used to compute PInverse.

Parameters

A	The matrix whose SVD needs to be computed

Friends And Related Function Documentation

friend class Friend

friend

Member Data Documentation

size_type nmrPInverseEconomyDynamicData::MMember

protected

size_type nmrPInverseEconomyDynamicData::NMember

protected

vctDynamicVector<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::OutputMemory

protected

Memory allocated for PInverse if needed.

vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::PInverseReference

protected

References to workspace or return types, these point either to user allocated memory or our memory chunks if needed

vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::SReference

protected

bool nmrPInverseEconomyDynamicData::StorageOrderMember

protected

vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::UReference

protected

vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::VtReference

protected

vctDynamicVector<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::WorkspaceMemory

protected

Memory allocated for Workspace matrices if needed This includes memory needed for SVD as well. Order of storage is m x m elements of U followed by n x n elements of Vt followed by min (m, n) elements of S, followed by memory for LAPACK workspace.

vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrPInverseEconomyDynamicData::WorkspaceReference

protected

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

/home/adeguet1/catkin_ws/src/cisst-saw/cisst/cisstNumerical/nmrPInverseEconomy.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