#include <nmrSVD.h>
Collaboration diagram for nmrSVDDynamicData:
The result of an SVD decomposition is composed of three different containers, the matrices U and V and the vector S defined by 
. 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 nmrSVDDynamicData 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 nmrSVDDynamicData.
Another good reason to use a "data" object is that the memory allocation can be performed once during an initialization phase while the function nmrSVD 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 nmrSVDDynamicData class allows 4 different configurations:
Definition at line 107 of file nmrSVD.h.
Type used for sizes within nmrSVDDynamicData. 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.
| typedef vctFixedSizeVector<size_type, 2> nmrSVDDynamicData::nsize_type |
| nmrSVDDynamicData::nmrSVDDynamicData | ( | ) | [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 410 of file nmrSVD.h.
References AllocateOutputWorkspace().
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.
| m,n | Dimension of the matrix to be decomposed. | |
| storageOrder | Storage order used for all matrices. |
Definition at line 430 of file nmrSVD.h.
References Allocate().
| nmrSVDDynamicData::nmrSVDDynamicData | ( | 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.
| A | input matrix |
Definition at line 448 of file nmrSVD.h.
References Allocate().
| nmrSVDDynamicData::nmrSVDDynamicData | ( | 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.
| A | input matrix | |
| inWorkspace | workspace |
Definition at line 468 of file nmrSVD.h.
References SetRefWorkspace().
| nmrSVDDynamicData::nmrSVDDynamicData | ( | 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.
| inU,inS,inVt | The output matrices and vector | |
| inWorkspace | The workspace for LAPACK. |
Definition at line 492 of file nmrSVD.h.
References SetRef().
| nmrSVDDynamicData::nmrSVDDynamicData | ( | 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.
| inU,inS,inVt | The output matrices and vector |
Definition at line 513 of file nmrSVD.h.
References SetRefOutput().
| void nmrSVDDynamicData::SetDimension | ( | size_type | m, | |
| size_type | n, | |||
| bool | storageOrder | |||
| ) | [inline, protected] |
Private method to set the data members MMember, NMember and StorageOrder. This method must be called before AllocateOutputWorkspace, ThrowUnlessOutputSizeIsCorrect or ThrowUnlessWorkspaceSizeIsCorrect.
Definition at line 155 of file nmrSVD.h.
References MMember, NMember, and StorageOrderMember.
Referenced by Allocate(), SetRef(), SetRefOutput(), and SetRefWorkspace().
| void nmrSVDDynamicData::AllocateOutputWorkspace | ( | bool | allocateOutput, | |
| bool | allocateWorkspace | |||
| ) | [inline, protected] |
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" (nmrSVDDynamicData) 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:
vctDynamicMatrix<double> A(20, 20); vctRandom(A, 10, 10); nmrSVDDynamicData data(A); // allocate output AND workspace vctDynamicVector<double> workspace(nmrSVDDynamicData::WorkspaceSize(A)); data.SetRefWorkspace(workspace); // after all, use my own workspace
Definition at line 183 of file nmrSVD.h.
References MMember, NMember, OutputMemory, vctDynamicMatrixRef< _elementType >::SetRef(), vctDynamicVectorRef< _elementType >::SetRef(), vctDynamicVector< _elementType >::SetSize(), SReference, StorageOrderMember, UReference, VtReference, WorkspaceMemory, WorkspaceReference, and WorkspaceSize().
Referenced by Allocate(), nmrSVDDynamicData(), SetRef(), SetRefOutput(), and SetRefWorkspace().
| void nmrSVDDynamicData::ThrowUnlessOutputSizeIsCorrect | ( | vctDynamicMatrixBase< _matrixOwnerTypeU, CISSTNETLIB_DOUBLE > & | inU, | |
| vctDynamicVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > & | inS, | |||
| vctDynamicMatrixBase< _matrixOwnerTypeVt, CISSTNETLIB_DOUBLE > & | inVt | |||
| ) | const throw (std::runtime_error) [inline, protected] |
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.
Definition at line 232 of file nmrSVD.h.
References cmnThrow(), MMember, NMember, and StorageOrderMember.
Referenced by SetRef(), and SetRefOutput().
| void nmrSVDDynamicData::ThrowUnlessWorkspaceSizeIsCorrect | ( | vctDynamicVectorBase< _vectorOwnerTypeWorkspace, CISSTNETLIB_DOUBLE > & | inWorkspace | ) | const throw (std::runtime_error) [inline, protected] |
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.
Definition at line 276 of file nmrSVD.h.
References cmnThrow(), MMember, NMember, and WorkspaceSize().
Referenced by SetRef(), and SetRefWorkspace().
Helper methods for user to set minimum working space required by LAPACK SVD routine.
| m,n | The size of matrix whose SVD needs to be computed. |
Definition at line 299 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), nmrSVD(), nmrPInverseDynamicData::SetRefSVD(), nmrPInverseDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), ThrowUnlessWorkspaceSizeIsCorrect(), and WorkspaceSize().
| static size_type nmrSVDDynamicData::WorkspaceSize | ( | vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | inA | ) | [inline, static] |
Helper method to determine the minimum working space required by LAPACK SVD routine.
| inA | The matrix whose SVD needs to be computed |
Definition at line 315 of file nmrSVD.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows(), and WorkspaceSize().
| static nsize_type nmrSVDDynamicData::MatrixSSize | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A | ) | [inline, static] |
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.
| A | The matrix to be decomposed using nmrSVD (it is used only to determine the sizes). |
Definition at line 330 of file nmrSVD.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), and vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows().
| static vctDynamicMatrixBase<_matrixOwnerTypeS, CISSTNETLIB_DOUBLE>& nmrSVDDynamicData::UpdateMatrixS | ( | const vctDynamicConstMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > & | A, | |
| const vctDynamicConstVectorBase< _vectorOwnerTypeS, CISSTNETLIB_DOUBLE > & | vectorS, | |||
| vctDynamicMatrixBase< _matrixOwnerTypeS, CISSTNETLIB_DOUBLE > & | matrixS | |||
| ) | throw (std::runtime_error) [inline, static] |
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).
| A | Matrix decomposed using nmrSVD. This is required to check the dimension of matrixS. | |
| vectorS | Vector of singular values as computed by nmrSVD. | |
| matrixS | Matrix with storage provided by the user. It must have the same size as A. |
Definition at line 348 of file nmrSVD.h.
References cmnThrow().
| void nmrSVDDynamicData::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 nmrSVDDynamicData object is passed on to nmrSVD function.
| A | The matrix for which SVD needs to be computed, size MxN |
Definition at line 533 of file nmrSVD.h.
References vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows(), and vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::StorageOrder().
Referenced by nmrSVDDynamicData().
| void nmrSVDDynamicData::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.
| A | The matrix for which SVD needs to be computed, size MxN. | |
| inWorkspace | The vector used for workspace by LAPACK. |
Definition at line 551 of file nmrSVD.h.
References AllocateOutputWorkspace(), vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::cols(), vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::rows(), SetDimension(), vctDynamicVectorRef< _elementType >::SetRef(), vctDynamicConstMatrixBase< _matrixOwnerType, _elementType >::StorageOrder(), ThrowUnlessWorkspaceSizeIsCorrect(), and WorkspaceReference.
Referenced by nmrSVDDynamicData().
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.
| m | Number of rows of input matrix A. | |
| n | Number of cols of input matrix A. | |
| storageOrder | Storage order of input matrix. One of VCT_COL_MAJOR or VCT_ROW_MAJOR. |
Definition at line 574 of file nmrSVD.h.
References AllocateOutputWorkspace(), and SetDimension().
| void nmrSVDDynamicData::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.
| inU,inS,inVt | The output matrices and vector. | |
| inWorkspace | The workspace. |
Definition at line 596 of file nmrSVD.h.
References AllocateOutputWorkspace(), SetDimension(), vctDynamicMatrixRef< _elementType >::SetRef(), vctDynamicVectorRef< _elementType >::SetRef(), SReference, ThrowUnlessOutputSizeIsCorrect(), ThrowUnlessWorkspaceSizeIsCorrect(), UReference, VtReference, and WorkspaceReference.
Referenced by nmrSVDDynamicData().
| void nmrSVDDynamicData::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.
| inU,inS,inVt | The output matrices and vector. |
Definition at line 625 of file nmrSVD.h.
References AllocateOutputWorkspace(), SetDimension(), vctDynamicMatrixRef< _elementType >::SetRef(), vctDynamicVectorRef< _elementType >::SetRef(), SReference, ThrowUnlessOutputSizeIsCorrect(), UReference, and VtReference.
Referenced by nmrSVDDynamicData().
| const vctDynamicVectorRef<CISSTNETLIB_DOUBLE>& nmrSVDDynamicData::S | ( | void | ) | const [inline] |
Const reference to the result vector S. This method must be called after the data has been computed by the nmrSVD function.
Definition at line 644 of file nmrSVD.h.
References SReference.
| const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrSVDDynamicData::U | ( | void | ) | const [inline] |
Const reference to the result matrix U. This method must be called after the data has been computed by the nmrSVD function.
Definition at line 651 of file nmrSVD.h.
References UReference.
| const vctDynamicMatrixRef<CISSTNETLIB_DOUBLE>& nmrSVDDynamicData::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 nmrSVD function.
Definition at line 657 of file nmrSVD.h.
References VtReference.
vctDynamicVector<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::WorkspaceMemory [protected] |
Memory allocated for Workspace matrices if needed.
Definition at line 123 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace().
vctDynamicVector<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::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.
Definition at line 130 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace().
vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::UReference [protected] |
References to workspace or return types, these point either to user allocated memory or our memory chunks if needed.
Definition at line 136 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetRef(), SetRefOutput(), and U().
vctDynamicMatrixRef<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::VtReference [protected] |
References to workspace or return types, these point either to user allocated memory or our memory chunks if needed.
Definition at line 137 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetRef(), SetRefOutput(), and Vt().
vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::SReference [protected] |
References to workspace or return types, these point either to user allocated memory or our memory chunks if needed.
Definition at line 138 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), S(), SetRef(), and SetRefOutput().
vctDynamicVectorRef<CISSTNETLIB_DOUBLE> nmrSVDDynamicData::WorkspaceReference [protected] |
References to workspace or return types, these point either to user allocated memory or our memory chunks if needed.
Definition at line 139 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetRef(), and SetRefWorkspace().
size_type nmrSVDDynamicData::MMember [protected] |
Just store M, N, and StorageOrder which are needed to check if A matrix passed to solve method matches the allocated size.
Definition at line 146 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetDimension(), ThrowUnlessOutputSizeIsCorrect(), and ThrowUnlessWorkspaceSizeIsCorrect().
size_type nmrSVDDynamicData::NMember [protected] |
Just store M, N, and StorageOrder which are needed to check if A matrix passed to solve method matches the allocated size.
Definition at line 147 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetDimension(), ThrowUnlessOutputSizeIsCorrect(), and ThrowUnlessWorkspaceSizeIsCorrect().
bool nmrSVDDynamicData::StorageOrderMember [protected] |
Just store M, N, and StorageOrder which are needed to check if A matrix passed to solve method matches the allocated size.
Definition at line 148 of file nmrSVD.h.
Referenced by AllocateOutputWorkspace(), SetDimension(), and ThrowUnlessOutputSizeIsCorrect().