cisst-saw
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes
nmrLU.h File Reference

Declaration of nmrLU. 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  nmrLUDynamicData
 Data of LU problem (Dynamic). More...
 
class  nmrLUDynamicData::Friend
 
class  nmrLUFixedSizeData< _rows, _cols >
 Data of LU problem (Fixed size). More...
 
class  nmrLUFixedSizeData< _rows, _cols >::Friend
 

Functions

Algorithm LU: Lower Upper Decomposition

These functions are different wrappers for the LAPACK function dgetrf. They compute an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges.

The factorization has the form $ A = P * L * U $ where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m > n), and U is upper triangular (upper trapezoidal if m < n).

These functions are wrappers around the LAPACK routine dgetrf, therefore they share some features with the LAPACK routine:

  1. On exit, the content of A is altered.
  2. The vectors and matrices must be compact, i.e. use a contiguous block of memory.

The nmrLU functions add the following features:

  1. A simplified interface to the cisstVector matrices, either vctDynamicMatrix or vctFixedSizeMatrix.
  2. 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.
  3. Helper classes to allocate memory for the output and workspace: nmrLUFixedSizeData and nmrLUDynamicData.
  4. Methods to create usable matrices P, L and U from the pivot indices and the resulting matrix A.

There are different ways to call this function to compute the LU of the matrix A. These correspond to different overloaded nmrLU functions:

  1. 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 nmrLUFixedSizeData or nmrLUDynamicData. corresponding to fixed size or dynamic matrix A:

    nmrLUDynamicData data(A);

    Call the nmrLU function:

    nmrLU(A, data);

    The content of input matrix A is modified by this routine and a vector the pivot indices has been updated. If the user needs the actual matrices P, L and U, he can use the different helper methods of the data:

    vctDynamicMatrix<CISSTNETLIB_DOUBLE> P, L, U;
    nmrLUDynamicData::SetSizeP(A, P);
    nmrLUDynamicData::SetSizeLU(A, L, U);
    nmrLUDynamicData::UpdateMatrixP(A, data.PivotIndices(), P);
    nmrLUDynamicData::UpdateMatrixLU(A, L, U);
    std::cout << P * L * U << std::endl;

    The matrices P, L and U can used any storage order since they are not used by LAPACK.

  2. The user provides the vector pivotIndices.

    The User allocates memory for this vector:

    vctDynamicMatrix<CISSTNETLIB_DOUBLE> A(5, 4, VCT_COL_MAJOR);
    vctRandom(A, -10.0, 10.0);
    vctDynamicVector<CISSTNETLIB_INTEGER> pivotIndices(4);

    Call the LU routine:

    nmrLU(A, pivotIndices);

    The LU function verifies that the size of the data objects matches the input.

  3. Using a data for fixed size containers.

    vctFixedSizeMatrix<CISSTNETLIB_DOUBLE, 5, 4, VCT_COL_MAJOR> A;
    vctRandom(A, -10.0, 10.0);
    typedef nmrLUFixedSizeData<4, 3> DataType;
    DataType data;
    nmrLU(A, data);
    typename DataType::MatrixTypeP P;
    typename DataType::MatrixTypeL L;
    typename DataType::MatrixTypeU U;
    DataType::UpdateMatrixP(data.PivotIndices(), P);
    DataType::UpdateMatrixLU(A, L, U);

Note
The LU functions make use of LAPACK routines. To activate this code, set the CISST_HAS_CNETLIB or CISST_HAS_CISSTNETLIB flag to ON during the configuration of cisst with CMake.
template<class _matrixOwnerType >
CISSTNETLIB_INTEGER nmrLU (vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &A, nmrLUDynamicData &data) throw (std::runtime_error)
 
template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >
CISSTNETLIB_INTEGER nmrLU (vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &A, vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &pivotIndices)
 
template<vct::size_type _rows, vct::size_type _cols, vct::size_type _minmn>
CISSTNETLIB_INTEGER nmrLU (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &A, vctFixedSizeVector< CISSTNETLIB_INTEGER, _minmn > &pivotIndices)
 
template<vct::size_type _rows, vct::size_type _cols>
CISSTNETLIB_INTEGER nmrLU (vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &A, nmrLUFixedSizeData< _rows, _cols > &data)
 

Detailed Description

Declaration of nmrLU.

Function Documentation

template<class _matrixOwnerType >
CISSTNETLIB_INTEGER nmrLU ( vctDynamicMatrixBase< _matrixOwnerType, CISSTNETLIB_DOUBLE > &  A,
nmrLUDynamicData &  data 
)
throw (std::runtime_error
)
inline

This function solves the LU problem for a dynamic matrix using an nmrLUDynamicData.

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. The result can be obtained via the const method nmrLUDynamicData::PivotIndices().

Parameters
AA matrix of size MxN, either vctDynamicMatrix or vctDynamicMatrixRef.
dataA data object corresponding to the input matrix.
Test:
nmrLUTest::TestDynamicDataColumnMajor nmrLUTest::TestDynamicUserOutputColumnMajor
template<class _matrixOwnerTypeA , class _vectorOwnerTypePivotIndices >
CISSTNETLIB_INTEGER nmrLU ( vctDynamicMatrixBase< _matrixOwnerTypeA, CISSTNETLIB_DOUBLE > &  A,
vctDynamicVectorBase< _vectorOwnerTypePivotIndices, CISSTNETLIB_INTEGER > &  pivotIndices 
)
inline

This function solves the LU problem for a dynamic matrix using the storage provided by the user for both the output (PivotIndices).

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

Parameters
Ais a reference to a dynamic matrix of size MxN
pivotIndicesVector created by the user to store the pivot indices.
Test:
nmrLUTest::TestDynamicUserOutputColumnMajor
template<vct::size_type _rows, vct::size_type _cols, vct::size_type _minmn>
CISSTNETLIB_INTEGER nmrLU ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &  A,
vctFixedSizeVector< CISSTNETLIB_INTEGER, _minmn > &  pivotIndices 
)
inline

This function solves the LU problem for a fixed size matrix using the storage provided by the user for the output (PivotIndices).

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. It stores the result in pivotIndices and A which now contains the elements of both L and U. The methods UpdateMatrixLU and UpdateMatrixP can ease the creation of more convenient matrices.

Parameters
Ais a fixed size matrix of size MxN.
pivotIndicesVector to store the pivot indices.
Test:
nmrLUTest::TestFixedSizeDataColumnMajorMLeqN nmrLUTest::TestFixedSizeDataColumnMajorMGeqN nmrLUTest::TestFixedSizeUserOutputColumnMajorMLeqN nmrLUTest::TestFixedSizeUserOutputColumnMajorMGeqN
template<vct::size_type _rows, vct::size_type _cols>
CISSTNETLIB_INTEGER nmrLU ( vctFixedSizeMatrix< CISSTNETLIB_DOUBLE, _rows, _cols, VCT_COL_MAJOR > &  A,
nmrLUFixedSizeData< _rows, _cols > &  data 
)
inline

This function solves the LU problem for a fixed size matrix using nmrLUFixedSizeData to allocate the memory required for the output:

vctFixedSizeMatrix<CISSTNETLIB_DOUBLE, 12, 7, VCT_COL_MAJOR> A;
vctRandom(A, -10.0, 10.0);
nmrLUFixedSizeData<12, 7> data;
nmrLU(A, data);
std::cout << "A: " << A << std::endl
<< "Pivot Indices: " << data.PivotIndices() << std::endl;

This method calls nmrLU(A, pivotIndices).

Parameters
AA fixed size matrix of size MxN.
dataA data object.
Test:
nmrLUTest::TestFixedSizeDataColumnMajorMLeqN nmrLUTest::TestFixedSizeDataColumnMajorMGeqN nmrLUTest::TestFixedSizeUserOutputColumnMajorMLeqN nmrLUTest::TestFixedSizeUserOutputColumnMajorMGeqN
Generated by   doxygen 1.8.6