cisst-saw
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
nmrSVDEconomyDynamicData Class Reference

Data for SVD problem (Dynamic). More...

#include <nmrSVDEconomy.h>

Classes

class  Friend
 

Public Types

typedef unsigned int size_type
 
typedef vctFixedSizeVector
< size_type, 2 > 
nsize_type
 

Public Member Functions

 nmrSVDEconomyDynamicData ()
 
 nmrSVDEconomyDynamicData (size_type m, size_type n, bool storageOrder)
 
template<class _matrixOwnerTypeA >
 nmrSVDEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)
 
template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >
 nmrSVDEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &inWorkspace)
 
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt , typename _vectorOwnerTypeWorkspace >
 nmrSVDEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &inU, vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &inS, vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &inVt, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &inWorkspace)
 
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
 nmrSVDEconomyDynamicData (vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &inU, vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &inS, vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &inVt)
 
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 > &inWorkspace)
 
void Allocate (size_type m, size_type n, bool storageOrder)
 
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt , typename _vectorOwnerTypeWorkspace >
void SetRef (vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &inU, vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &inS, vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &inVt, vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &inWorkspace) throw (std::runtime_error)
 
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
void SetRefOutput (vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &inU, vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &inS, vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &inVt) throw (std::runtime_error)
 
const vctDynamicVectorRef
< CISSTNETLIB_DOUBLE > & 
S (void) const
 
const vctDynamicMatrixRef
< CISSTNETLIB_DOUBLE > & 
U (void) const
 
const vctDynamicMatrixRef
< CISSTNETLIB_DOUBLE > & 
Vt (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 > &inA)
 
template<class _matrixOwnerTypeA >
static nsize_type MatrixSSize (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A)
 
template<class _matrixOwnerTypeA , class _matrixOwnerTypeS , class _vectorOwnerTypeS >
static vctDynamicMatrixBase
< _matrixOwnerTypeS,
CISSTNETLIB_DOUBLE > & 
UpdateMatrixS (const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, const vctDynamicConstVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &vectorS, vctDynamicMatrixBase< _matrixOwnerTypeS, CISSTNETLIB_DOUBLE > &matrixS) throw (std::runtime_error)
 

Protected Member Functions

void SetDimension (size_type m, size_type n, bool storageOrder)
 
void AllocateOutputWorkspace (bool allocateOutput, bool allocateWorkspace)
 
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
void ThrowUnlessOutputSizeIsCorrect (vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &inU, vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &inS, vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &inVt) const throw (std::runtime_error)
 
template<typename _vectorOwnerTypeWorkspace >
void ThrowUnlessWorkspaceSizeIsCorrect (vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &inWorkspace) const throw (std::runtime_error)
 

Protected Attributes

vctDynamicVector
< CISSTNETLIB_DOUBLE > 
WorkspaceMemory
 
vctDynamicVector
< CISSTNETLIB_DOUBLE > 
OutputMemory
 
vctDynamicMatrixRef
< CISSTNETLIB_DOUBLE > 
UReference
 
vctDynamicMatrixRef
< CISSTNETLIB_DOUBLE > 
VtReference
 
vctDynamicVectorRef
< CISSTNETLIB_DOUBLE > 
SReference
 
vctDynamicVectorRef
< CISSTNETLIB_DOUBLE > 
WorkspaceReference
 
size_type MMember
 
size_type NMember
 
bool StorageOrderMember
 

Friends

class Friend
 

Detailed Description

Data for SVD problem (Dynamic).

The result of an SVD decomposition is composed of three different containers, the matrices U and V and the vector S defined by $ A = U * \Sigma * V^{T} $. The sizes of these components must match exactly the input matrix A. To ease the use of the SVD routine, the user can rely on the nmrSVDEconomyDynamicData class to perform the required memory allocation. Furthermore, the underlying Fortran routine from LAPACK requires a workspace (aka a scratch space). This workspace can also be allocated by the nmrSVDEconomyDynamicData.

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

The SVD routine is somewhat specific in the sens that is can be used on either storage order, row major or column major, without any copy or transpose. Nevertheless, the current implementation requires all the matrices to use the same storage order, i.e. if A is row major, both U and Vt must be stored row first. 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 nmrSVDEconomyDynamicData class allows 4 different configurations:

See Also
nmrSVDEconomy

Member Typedef Documentation

Matrix size type, i.e. vector of two elements: number of rows and columns.

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

nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( )
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
nmrSVDEconomyDynamicData::Allocate nmrSVDEconomyDynamicData::SetRefOutput nmrSVDEconomyDynamicData::SetRefWorkspace nmrSVDEconomyDynamicData::SetRef
nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( size_type  m,
size_type  n,
bool  storageOrder 
)
inline

Constructor where the user specifies the size and storage order. Memory allocation is performed for the output matrices and vectors as well as Workspace used by LAPACK. This should be used when the user doesn't care much about where the output should be stored and doesn't need to share the workspace between different algorithms.

Parameters
m,nDimension of the matrix to be decomposed.
storageOrderStorage order used for all matrices.
See Also
nmrSVDEconomyDynamicData::Allocate
template<class _matrixOwnerTypeA >
nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( 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 the output matrices and vectors as well as Workspace used by LAPACK. This should be used when the user doesn't care much about where the output should be stored and doesn't need to share the workspace between different algorithms.

Parameters
Ainput matrix
See Also
nmrSVDEconomyDynamicData::Allocate
template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >
nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A,
vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  inWorkspace 
)
inline

Constructor where the user provides the input matrix to specify the size and storage order. Memory allocation is performed for the output matrices and vectors only. This constructor should be used when the user cares wants to avoid allocating different workspaces for different numerical routines. Please note that since multiple routines can share the workspace, these routines must be called in a thread safe manner.

Parameters
Ainput matrix
inWorkspaceworkspace
See Also
nmrSVDEconomyDynamicData::SetRefWorkspace
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt , typename _vectorOwnerTypeWorkspace >
nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &  inU,
vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  inS,
vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &  inVt,
vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  inWorkspace 
)
inline

Constructor where the user provides the matrices U, Vt and vectors S as well as the workspace. The data object now acts as a composite container to hold, pass and manipulate a convenient storage for SVD algorithm. Checks are made on the validity of the input and its consitency in terms of size ans storage order. Please note that since the workspace and the input are now created by the user, special attention must be given to thread safety issues.

Parameters
inU,inS,inVtThe output matrices and vector
inWorkspaceThe workspace for LAPACK.
See Also
nmrSVDEconomyDynamicData::SetRef
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
nmrSVDEconomyDynamicData::nmrSVDEconomyDynamicData ( vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &  inU,
vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  inS,
vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &  inVt 
)
inline

Constructor where the user provides the matrices U, Vt and vectors S. The workspace will be allocated and managed by the "data". This constructor should be used when the user already has a storage for the data but doesn't care much about the workspace.

Parameters
inU,inS,inVtThe output matrices and vector
See Also
nmrSVDEconomyDynamicData::SetRefOutput

Member Function Documentation

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

This method allocates memory for the output matrices and vector as well as the workspace. The input matrix is used only to determine the size of the problem as well as the storage order (i.e. VCT_ROW_MAJOR or VCT_COL_MAJOR).

This method should be called before the nmrSVDEconomyDynamicData object is passed on to nmrSVDEconomy function.

Parameters
AThe matrix for which SVD needs to be computed, size MxN
void nmrSVDEconomyDynamicData::Allocate ( size_type  m,
size_type  n,
bool  storageOrder 
)
inline

This method allocates the memory for the output matrices and vector as well as the workspace. This method is not meant to be a top-level user API, but is used by other overloaded Allocate methods.

Parameters
mNumber of rows of input matrix A.
nNumber of cols of input matrix A.
storageOrderStorage order of input matrix. One of VCT_COL_MAJOR or VCT_ROW_MAJOR.
void nmrSVDEconomyDynamicData::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" (nmrSVDEconomyDynamicData) 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). For example:

vctRandom(A, 10, 10);
nmrSVDEconomyDynamicData data(A); // allocate output AND workspace
data.SetRefWorkspace(workspace); // after all, use my own workspace
Note
The method SetDimension must have been called before.
template<class _matrixOwnerTypeA >
static nsize_type nmrSVDEconomyDynamicData::MatrixSSize ( const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A)
inlinestatic

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

Parameters
AThe matrix to be decomposed using nmrSVDEconomy (it is used only to determine the sizes).
const vctDynamicVectorRef<CISSTNETLIB_DOUBLE>& nmrSVDEconomyDynamicData::S ( void  ) const
inline

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

void nmrSVDEconomyDynamicData::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<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt , typename _vectorOwnerTypeWorkspace >
void nmrSVDEconomyDynamicData::SetRef ( vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &  inU,
vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  inS,
vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &  inVt,
vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  inWorkspace 
)
throw (std::runtime_error
)
inline

This method doesn't allocate any memory as it relies on user provided matrices and vectors for the output as well as the workspace.

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

Parameters
inU,inS,inVtThe output matrices and vector.
inWorkspaceThe workspace.
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
void nmrSVDEconomyDynamicData::SetRefOutput ( vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &  inU,
vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  inS,
vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &  inVt 
)
throw (std::runtime_error
)
inline

This method allocates the memory for the workspace. The output memory is provided by the user. The method computes the size of the problem based on the user provided output and verifies that the output components (inU, inS, and inVt) are consistent with respect to their size and storage order.

Parameters
inU,inS,inVtThe output matrices and vector.
template<class _matrixOwnerTypeA , class _vectorOwnerTypeWorkspace >
void nmrSVDEconomyDynamicData::SetRefWorkspace ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A,
vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  inWorkspace 
)
inline

This method allocates the memory for the output matrices and vector and uses the memory provided by user for workspace. The input matrix A is used to determine the size of the problem as well as the storage order.

This method verifies that the workspace provided by the user is large enough and is compact.

Parameters
AThe matrix for which SVD needs to be computed, size MxN.
inWorkspaceThe vector used for workspace by LAPACK.
template<typename _matrixOwnerTypeU , typename _vectorOwnerTypeS , typename _matrixOwnerTypeVt >
void nmrSVDEconomyDynamicData::ThrowUnlessOutputSizeIsCorrect ( vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > &  inU,
vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  inS,
vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > &  inVt 
) const
throw (std::runtime_error
)
inlineprotected

Verifies that the user provided references for the output match the size of the "data" as set by SetDimension. This method also checks that the storage orders are consistent across the provided matrices and that all containers are compact.

Note
The method SetDimension must have been called before.
template<typename _vectorOwnerTypeWorkspace >
void nmrSVDEconomyDynamicData::ThrowUnlessWorkspaceSizeIsCorrect ( vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > &  inWorkspace) 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>& nmrSVDEconomyDynamicData::U ( void  ) const
inline

Const reference to the result matrix U. This method must be called after the data has been computed by the nmrSVDEconomy function.

template<class _matrixOwnerTypeA , class _matrixOwnerTypeS , class _vectorOwnerTypeS >
static vctDynamicMatrixBase<_matrixOwnerTypeS, CISSTNETLIB_DOUBLE>& nmrSVDEconomyDynamicData::UpdateMatrixS ( const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A,
const vctDynamicConstVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > &  vectorS,
vctDynamicMatrixBase< _matrixOwnerTypeS, CISSTNETLIB_DOUBLE > &  matrixS 
)
throw (std::runtime_error
)
inlinestatic

Fill a matrix from the singular values. Sets all the elements to zero and then replace the diagonal by the singular values (provided by vectorS).

Parameters
AMatrix decomposed using nmrSVDEconomy. This is required to check the dimension of matrixS.
vectorSVector of singular values as computed by nmrSVDEconomy.
matrixSMatrix with storage provided by the user. It must have the same size as A.
const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrSVDEconomyDynamicData::Vt ( void  ) const
inline

Const reference to the result matrix Vt (V transposed). This method must be called after the data has been computed by the nmrSVDEconomy function.

static size_type nmrSVDEconomyDynamicData::WorkspaceSize ( size_type  m,
size_type  n 
)
inlinestatic

Helper methods for user to set minimum working space required by LAPACK SVD routine.

Parameters
m,nThe size of matrix whose SVD needs to be computed.
template<class _matrixOwnerTypeA >
static size_type nmrSVDEconomyDynamicData::WorkspaceSize ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  inA)
inlinestatic

Helper method to determine the minimum working space required by LAPACK SVD routine.

Parameters
inAThe matrix whose SVD needs to be computed

Friends And Related Function Documentation

friend class Friend
friend

Member Data Documentation

size_type nmrSVDEconomyDynamicData::MMember
protected

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

size_type nmrSVDEconomyDynamicData::NMember
protected
vctDynamicVector<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::OutputMemory
protected

Memory allocated for U, Vt Matrices and Vector S if needed. This method allocates a single block of memory for these 3 containers; m x m elements of U followed by n x n elements of Vt followed by min (m, n) elements of S.

vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::SReference
protected
bool nmrSVDEconomyDynamicData::StorageOrderMember
protected
vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::UReference
protected

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

vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::VtReference
protected
vctDynamicVector<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::WorkspaceMemory
protected

Memory allocated for Workspace matrices if needed.

vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrSVDEconomyDynamicData::WorkspaceReference
protected

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