RWSVDecomp< TypeT, SVDCalc > Class Template Reference
[Decomposition]

Used to construct and work with singular value decompositions. More...

#include <rw/lapack/sv.h>

Inheritance diagram for RWSVDecomp< TypeT, SVDCalc >:

List of all members.

Public Types
typedef rw_numeric_traits < TypeT >::norm_type	norm_type
Public Member Functions
	RWSVDecomp ()
	RWSVDecomp (const RWSVDecomp< TypeT, SVDCalc > &A)
	RWSVDecomp (const RWGenMat< TypeT > &A, norm_type tol=0)
void	factor (const RWGenMat< TypeT > &A, norm_type tol=0)
void	operator= (const RWSVDecomp< TypeT, SVDCalc > &x)
unsigned	cols () const
norm_type	singularValue (int i) const
const RWMathVec< norm_type >	singularValues () const
const RWMathVec< TypeT >	leftVector (int i) const
const RWGenMat< TypeT >	leftVectors () const
bool	good () const
bool	fail () const
unsigned	numLeftVectors () const
unsigned	numRightVectors () const
unsigned	rank () const
const RWMathVec< TypeT >	rightVector (int i) const
const RWGenMat< TypeT >	rightVectors () const
unsigned	rows () const
void	truncate (norm_type tol)

---

Detailed Description

template<class TypeT, class SVDCalc>
class RWSVDecomp< TypeT, SVDCalc >

A singular value decomposition is a representation of a matrix A of the form:

where U and V are orthogonal, and E is diagonal. The entries along the diagonal of E are the singular values; the columns of U are the left singular vectors, and the columns of V are the right singular vectors.

The class RWSVDecomp<T> is used to construct and work with singular value decompositions. The singular values are always ordered smallest to largest with this class. You may need more control over the computation of the decomposition than is provided by this class. For example, if you don't need all the singular vectors, you can use the SV decomposition server class, RWSVServer<T> , to do the construction.

The template parameter <SVDCalc> determines the algorithm used by the RWSVDecomp<T> class to compute the singular value decomposition and must implement the following method:

Note:

For greater flexibility, the user can implement this method, or the Linear Algebra Module provides two classes to perform this function - RWSVDCalc<T> and RWSVDDivConqCalc<T>. Please see their descriptions for more information.

 bool computeSVD(const RWGenMat<T>&   A,                      
                       RWGenMat<T>&   U,                     
                       RWGenMat<T>&  VT,                   
                       RWMathVec<norm_type>&  sigma,               
                       norm_type  tolerance, 
                   int numLeftVectors = -1,                             
                   int numRightVectors = -1); 

where norm_type is a typedef for rw_numeric_traits<T>::norm_type.

Parameters:

A - The input matrix for which the singular value decomposition is being computed.

U - The output matrix of left singular victors (the columns of U are the left singular vectors).

VT - The output matrix of right singular victors (the rows of VT are the right singular victors).

sigma - The output vector of singular values in descending order.

tolerance - The input singular values with magnitude less than tolerance will be set to zero.

numLeftVectors - The input number of left vectors to compute. If the number is less than zero, the default number of vectors will be computed (it is up to the developer to determine what the default is).

numRightVectors - The input number of right vectors to compute. If the number is less than zero, the default number of vectors will be computed (it is up to the developer to determine what the default is).

The return value is true if the decomposition was successfully computed.

Synopsis

 #include <rw/lapack/sv.h>
 #include <rw/lapack/svddccalc.h>
 
 RWGenMat<double> A;
 .
 .
 .
 RWSVDecomp<double,RWSVDDivConqCalc<double> >sv(A);

Examples

 #include <rw/iostream>
 #include <rw/lapack/sv.h>
 #include <rw/lapack/svddccalc.h>
 
 int main()
 {
     RWGenMat<double> A;
     std::cin >> A;
     RWSVDecomp<double, RWSVDDivConqCalc<double> >
                        sv(A);
     std::cout << "Input matrix: " << A << std::endl;
     std::cout << "singular values: " <<
                  sv.singularValues() << std::endl;
     std::cout << "left vectors: " << sv.leftVectors()
               << std::endl;
     std::cout << "right vectors: " << sv.rightVectors()
               << std::endl;
     return 0;
 }

---

Member Typedef Documentation

template<class TypeT, class SVDCalc>

typedef rw_numeric_traits<TypeT>::norm_type RWSVDecomp< TypeT, SVDCalc >::norm_type

Typedef for the usual return type of numerical norm-like functions. For more information, see rw_numeric_traits<T>::norm_type.

---

Constructor & Destructor Documentation

template<class TypeT, class SVDCalc>

RWSVDecomp< TypeT, SVDCalc >::RWSVDecomp

(

)

Default constructor. Builds a decomposition of size 0 x 0.

template<class TypeT, class SVDCalc>

RWSVDecomp< TypeT, SVDCalc >::RWSVDecomp

(

const RWSVDecomp< TypeT, SVDCalc > &

A

)

Copy constructor. References the data in the original decomposition for efficiency.

template<class TypeT, class SVDCalc>

RWSVDecomp< TypeT, SVDCalc >::RWSVDecomp	(	const RWGenMat< TypeT > &	A,
		norm_type	tol = 0
	)

Builds a singular value decomposition of A. The parameter tol specifies the accuracy to which the singular values are required. By default, they are computed to within machine precision. To construct a singular value decomposition with non-default options, you can use the singular value decomposition server classes RWSVServer<T> .

---

Member Function Documentation

template<class TypeT, class SVDCalc>

unsigned RWSVDecomp< TypeT, SVDCalc >::cols

(

)

const [inline]

Returns the number of columns in the matrix that the decomposition represents.

template<class TypeT, class SVDCalc>

void RWSVDecomp< TypeT, SVDCalc >::factor	(	const RWGenMat< TypeT > &	A,
		norm_type	tol = 0
	)

Builds a singular value decomposition of A. The parameter tol specifies the accuracy to which the singular values are required. By default, they are computed to within machine precision. To construct a singular value decomposition with non-default options, you can use the singular value decomposition server class RWSVServer<T> .

template<class TypeT, class SVDCalc>

bool RWSVDecomp< TypeT, SVDCalc >::fail

(

)

const [inline]

Returns an indication of whether all singular values are successfully computed.

template<class TypeT, class SVDCalc>

bool RWSVDecomp< TypeT, SVDCalc >::good

(

)

const [inline]

Returns an indication of whether all singular values are successfully computed.

template<class TypeT, class SVDCalc>

const RWMathVec<TypeT> RWSVDecomp< TypeT, SVDCalc >::leftVector

(

int

i

)

const

Returns the i ^th left singular vector. Throws an exception if the i ^th vector is not computed.

template<class TypeT, class SVDCalc>

const RWGenMat<TypeT> RWSVDecomp< TypeT, SVDCalc >::leftVectors

(

)

const [inline]

Returns a matrix whose columns are the left singular vectors.

template<class TypeT, class SVDCalc>

unsigned RWSVDecomp< TypeT, SVDCalc >::numLeftVectors

(

)

const [inline]

Returns the number of left singular vectors computed.

template<class TypeT, class SVDCalc>

unsigned RWSVDecomp< TypeT, SVDCalc >::numRightVectors

(

)

const [inline]

Returns the number of right singular vectors computed.

template<class TypeT, class SVDCalc>

void RWSVDecomp< TypeT, SVDCalc >::operator=

(

const RWSVDecomp< TypeT, SVDCalc > &

x

)

Assigns the passed value to this decomposition. The current contents of the decomposition are lost.

template<class TypeT, class SVDCalc>

unsigned RWSVDecomp< TypeT, SVDCalc >::rank

(

)

const [inline]

Returns the rank of the matrix. The rank is indicated by the number of nonzero singular values.

template<class TypeT, class SVDCalc>

const RWMathVec<TypeT> RWSVDecomp< TypeT, SVDCalc >::rightVector

(

int

i

)

const

Returns the i ^th right singular vector. Throws an exception if the i ^th vector is not computed.

template<class TypeT, class SVDCalc>

const RWGenMat<TypeT> RWSVDecomp< TypeT, SVDCalc >::rightVectors

(

)

const [inline]

Returns a matrix whose columns are the right singular vectors.

template<class TypeT, class SVDCalc>

unsigned RWSVDecomp< TypeT, SVDCalc >::rows

(

)

const [inline]

Returns the number of rows in the matrix that the decomposition represents.

template<class TypeT, class SVDCalc>

norm_type RWSVDecomp< TypeT, SVDCalc >::singularValue

(

int

i

)

const

Returns the i ^th singular value.

template<class TypeT, class SVDCalc>

const RWMathVec<norm_type> RWSVDecomp< TypeT, SVDCalc >::singularValues

(

)

const [inline]

Returns the vector of singular values.

template<class TypeT, class SVDCalc>

void RWSVDecomp< TypeT, SVDCalc >::truncate

(

norm_type

tol

)

Truncates all singular values with magnitude less than tol by setting them to 0. If tol is a measure of the expected error in entries of the matrix, this truncation provides a more meaningful decomposition. The rank of the decomposition is a measure of the numerical rank of the matrix.