RWUpperTriMat< TypeT > Class Template Reference

Encapsulates upper triangular matrices, which are 0 above the diagonal. More...

#include <rw/lapack/utrimat.h>

Public Member Functions
	RWUpperTriMat ()
	RWUpperTriMat (const RWUpperTriMat< TypeT > &rhs)
	RWUpperTriMat (unsigned n, unsigned nAgain)
	RWUpperTriMat (const RWMathVec< TypeT > &data, unsigned n, unsigned nAgain)
	RWUpperTriMat (const typename rw_linear_algebra_traits< TypeT >::narrow_upper_tri_mat &re)
	RWUpperTriMat (const RWUpperTriMat< double > &re, const RWUpperTriMat< double > &im)
	~RWUpperTriMat ()
RWRORef< TypeT >	bcref (int i, int j)
TypeT	bcset (int i, int j, TypeT x)
TypeT	bcval (int i, int j) const
unsigned	binaryStoreSize () const
unsigned	cols () const
RWUpperTriMat< TypeT >	copy () const
TypeT *	data ()
const TypeT *	data () const
RWMathVec< TypeT >	dataVec ()
const RWMathVec< TypeT > &	dataVec () const
RWUpperTriMat< TypeT >	deepCopy () const
void	deepenShallowCopy ()
RWUpperTriMat< TypeT >	leadingSubmatrix (int k)
bool	operator!= (const RWUpperTriMat< TypeT > &X)
RWRORef< TypeT >	operator() (int i, int j)
TypeT	operator() (int i, int j) const
RWUpperTriMat< TypeT > &	operator*= (const RWUpperTriMat< TypeT > &m)
RWUpperTriMat< TypeT > &	operator*= (TypeT v)
RWUpperTriMat< TypeT > &	operator+= (const RWUpperTriMat< TypeT > &m)
RWUpperTriMat< TypeT > &	operator-= (const RWUpperTriMat< TypeT > &m)
RWUpperTriMat< TypeT > &	operator/= (const RWUpperTriMat< TypeT > &m)
RWUpperTriMat< TypeT > &	operator/= (TypeT v)
RWUpperTriMat< TypeT > &	operator= (const RWUpperTriMat< TypeT > &A)
bool	operator== (const RWUpperTriMat< TypeT > &X)
void	printOn (std::ostream &os) const
RWRORef< TypeT >	ref (int i, int j)
RWUpperTriMat< TypeT > &	reference (RWUpperTriMat< TypeT > &m)
void	resize (unsigned m, unsigned n)
void	restoreFrom (RWvistream &is)
void	restoreFrom (RWFile &f)
unsigned	rows () const
void	saveOn (RWvostream &os) const
void	saveOn (RWFile &f) const
void	scanFrom (std::istream &is)
TypeT	set (int i, int j, TypeT x)
TypeT	val (int i, int j) const
void	zero ()

Related Functions
(Note that these are not member functions.)
template<class TypeT >
RWUpperTriMat< typename rw_numeric_traits< TypeT >::norm_type >	abs (const RWUpperTriMat< TypeT > &A)
RWUpperTriMat< double >	arg (const RWUpperTriMat< DComplex > &A)
template<class TypeT >
RWUpperTriMat< TypeT >	conj (const RWUpperTriMat< TypeT > &A)
RWUpperTriMat< double >	imag (const RWUpperTriMat< DComplex > &A)
double	maxValue (const RWUpperTriMat< double > &A)
float	maxValue (const RWUpperTriMat< float > &A)
double	minValue (const RWUpperTriMat< double > &A)
float	minValue (const RWUpperTriMat< float > &A)
RWUpperTriMat< double >	norm (const RWUpperTriMat< DComplex > &A)
template<class TypeT >
RWUpperTriMat< TypeT >	operator* (const RWUpperTriMat< TypeT > &, const RWUpperTriMat< TypeT > &)
template<class TypeT >
RWUpperTriMat< TypeT >	operator* (const RWUpperTriMat< TypeT > &A, TypeT x)
template<class TypeT >
RWUpperTriMat< TypeT >	operator* (TypeT x, const RWUpperTriMat< TypeT > &A)
template<class TypeT >
RWUpperTriMat< TypeT >	operator+ (const RWUpperTriMat< TypeT > &m)
template<class TypeT >
RWUpperTriMat< TypeT >	operator+ (const RWUpperTriMat< TypeT > &, const RWUpperTriMat< TypeT > &)
template<class TypeT >
RWUpperTriMat< TypeT >	operator- (const RWUpperTriMat< TypeT > &m)
template<class TypeT >
RWUpperTriMat< TypeT >	operator- (const RWUpperTriMat< TypeT > &, const RWUpperTriMat< TypeT > &)
template<class TypeT >
RWUpperTriMat< TypeT >	operator/ (const RWUpperTriMat< TypeT > &, const RWUpperTriMat< TypeT > &)
template<class TypeT >
RWUpperTriMat< TypeT >	operator/ (const RWUpperTriMat< TypeT > &A, TypeT x)
template<class TypeT >
std::ostream &	operator<< (std::ostream &s, const RWUpperTriMat< TypeT > &m)
template<class TypeT >
std::istream &	operator>> (std::istream &s, RWUpperTriMat< TypeT > &m)
template<class TypeT >
RWMathVec< TypeT >	product (const RWUpperTriMat< TypeT > &A, const RWMathVec< TypeT > &x)
template<class TypeT >
RWMathVec< TypeT >	product (const RWMathVec< TypeT > &x, const RWUpperTriMat< TypeT > &A)
RWUpperTriMat< double >	real (const RWUpperTriMat< DComplex > &A)
template<class TypeT >
RWUpperTriMat< TypeT >	toUpperTriMat (const RWGenMat< TypeT > &A)
template<class TypeT >
RWLowerTriMat< TypeT >	transpose (const RWUpperTriMat< TypeT > &)

Detailed Description

template<class TypeT>
class RWUpperTriMat< TypeT >

The class RWUpperTriMat encapsulates upper triangular matrices. An upper triangular matrix is 0 above the diagonal.

Synopsis

#include <rw/lapack/utrimat.h>

RWUpperTriMat<double>;

Example

#include <rw/lapack/utrimat.h>

int main()
{
    RWUpperTriMat<double> U(5,5);
    RWLowerTriMat<double> L = transpose(U);

    return 0;
}

Storage Scheme

The matrix is stored column-by-column. For example, the matrix:

\[ \begin{bmatrix} A_{11} & A_{12} & A_{13} & ...A_{1n} \\ 0 & A_{22} & A_{23} & ...A_{2n} \\ 0 & 0 & A_{33} & ...A_{3n} \\ & & . & \\ & & . & \\ & & . & \\ 0 & 0 & 0 & ...A_{nn} \end{bmatrix} \]

is stored as follows:

[ A11
  A12 A22
  A13 A23 A33
  ...
  A1n A2n A3n
                            ... Ann ]

The mapping between the array and storage vector is as follows:

\[ A(i+1,j+1) \rightarrow vec \left [\frac{j(j+1)}{2+i} \right ] \]

Constructor & Destructor Documentation

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat

(

)

Default constructor. Builds a matrix of size 0 x 0. This constructor is necessary to declare a matrix with no explicit constructor or to declare an array of matrices.

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat

(

const RWUpperTriMat< TypeT > &

rhs

)

Builds a copy of its argument, rhs. Note that the new matrix references the data of rhs. To construct a matrix with its own copy of the data, you can use copy() or deepenShallowCopy().

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat	(	unsigned	n,
		unsigned	nAgain
	)

Defines an uninitialized matrix of size n x n.

Note

This constructor is used, rather than a constructor that takes only a single argument, to avoid type conversion problems. Both arguments must be equal or a runtime error occurs.

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat	(	const RWMathVec< TypeT > &	data,
		unsigned	n,
		unsigned	nAgain
	)

Constructs a size n x n matrix using the data in the passed vector. This data must be stored in the format described in the Storage Scheme section. The resultant matrix references the data in vector data.

Note

This constructor is used, rather than a constructor that takes only a single argument, to avoid type conversion problems. The last two arguments must be equal or a runtime error occurs.

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat

(

const typename rw_linear_algebra_traits< TypeT >::narrow_upper_tri_mat &

re

)

Constructs a complex matrix from the real part supplied. The imaginary part is assumed to be 0.

template<class TypeT>

RWUpperTriMat< TypeT >::RWUpperTriMat	(	const RWUpperTriMat< double > &	re,
		const RWUpperTriMat< double > &	im
	)

Constructs a complex matrix from the real and imaginary parts supplied.

template<class TypeT>

RWUpperTriMat< TypeT >::~RWUpperTriMat

(

)

Destructor.

Member Function Documentation

template<class TypeT>

RWRORef<TypeT> RWUpperTriMat< TypeT >::bcref	(	int	i,
		int	j
	)

Returns a reference to the ij ^th element of the matrix, after doing bounds checking.

template<class TypeT>

TypeT RWUpperTriMat< TypeT >::bcset	(	int	i,
		int	j,
		TypeT	x
	)

Sets the ij ^th element of the matrix equal to x, after doing bounds checking.

template<class TypeT>

TypeT RWUpperTriMat< TypeT >::bcval	(	int	i,
		int	j
	)		const

Returns the value of the ij ^th element of the matrix, after doing bounds checking.

template<class TypeT>

unsigned RWUpperTriMat< TypeT >::binaryStoreSize

(

)

const

Returns the number of bytes that it would take to write the matrix to a file using saveOn().

template<class TypeT>

unsigned RWUpperTriMat< TypeT >::cols ( ) const

inline

Returns the number of columns in the matrix.

template<class TypeT>

RWUpperTriMat<TypeT> RWUpperTriMat< TypeT >::copy

(

)

const

Creates a copy of this matrix with distinct data. The stride of the data vector in the new matrix is guaranteed to be 1.

template<class TypeT>

TypeT* RWUpperTriMat< TypeT >::data ( void  )

inline

Returns a pointer to the first item of data in the vector storing the matrix's data. You can use this (with caution!) to pass the matrix's data to C or FORTRAN subroutines. Be aware that the stride of the data vector may not be 1.

template<class TypeT>

const TypeT* RWUpperTriMat< TypeT >::data ( void  ) const

inline

Returns a pointer to the first item of data in the vector storing the matrix's data. You can use this (with caution!) to pass the matrix's data to C or FORTRAN subroutines. Be aware that the stride of the data vector may not be 1.

template<class TypeT>

RWMathVec<TypeT> RWUpperTriMat< TypeT >::dataVec ( )

inline

Returns the matrix's data vector. This is where the explicitly stored entries in the matrix are kept.

template<class TypeT>

const RWMathVec<TypeT>& RWUpperTriMat< TypeT >::dataVec ( ) const

inline

Returns the matrix's data vector. This is where the explicitly stored entries in the matrix are kept.

template<class TypeT>

RWUpperTriMat<TypeT> RWUpperTriMat< TypeT >::deepCopy ( ) const

inline

Creates a copy of this matrix with distinct data. The stride of the data vector in the new matrix is guaranteed to be 1.

template<class TypeT>

void RWUpperTriMat< TypeT >::deepenShallowCopy ( )

inline

Ensures that the data in the matrix is not shared by any other matrix or vector. Also ensures that the stride in the data vector is equal to 1. If necessary, a new copy of the data vector is made.

template<class TypeT>

RWUpperTriMat<TypeT> RWUpperTriMat< TypeT >::leadingSubmatrix

(

int

k

)

Returns the k x k upper left corner of the matrix. The submatrix and the matrix share the same data.

template<class TypeT>

bool RWUpperTriMat< TypeT >::operator!= ( const RWUpperTriMat< TypeT > &  X )

inline

Inequality operator. Returns false if two matrices have the same size and their elements are all exactly the same. Otherwise this function returns true. Be aware that floating point arithmetic is not exact; matrices that are theoretically equal are not always numerically equal.

template<class TypeT >

RWRORef< TypeT > RWUpperTriMat< TypeT >::operator() ( int  i, int  j  )

inline

Accesses the ij ^th element. A reference type is returned, so this operator can be used for assigning or accessing an element. In this case, using this operator is equivalent to calling the ref() member function. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined before including the header file.

template<class TypeT >

TypeT RWUpperTriMat< TypeT >::operator() ( int  i, int  j  ) const

inline

Accesses the ij ^th element. A value is returned, so this operator can be used only for accessing an element. Using this operator is equivalent to calling the val() member function. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined before including the header file.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator*=

(

const RWUpperTriMat< TypeT > &

m

)

Performs element-by-element arithmetic on the data in the matrices. This function does element-by-element multiplication, not inner product style matrix multiplication. You can use the product() global function to do matrix-matrix inner product multiplication.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator*=

(

TypeT

v

)

Performs the indicated operation on each element of the matrix.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator+=

(

const RWUpperTriMat< TypeT > &

m

)

Performs element-by-element arithmetic on the data in the matrices.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator-=

(

const RWUpperTriMat< TypeT > &

m

)

Performs element-by-element arithmetic on the data in the matrices.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator/=

(

const RWUpperTriMat< TypeT > &

m

)

Performs element-by-element arithmetic on the data in the matrices.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator/=

(

TypeT

v

)

Performs the indicated operation on each element of the matrix.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::operator=

(

const RWUpperTriMat< TypeT > &

A

)

Sets the matrix elements equal to the elements of A. The two matrices must be the same size. To make the matrix reference the same data as A, use reference().

template<class TypeT>

bool RWUpperTriMat< TypeT >::operator==

(

const RWUpperTriMat< TypeT > &

X

)

Equality operator. Returns true if two matrices have the same size and their elements are all exactly the same. Otherwise this function returns false. Be aware that floating point arithmetic is not exact; matrices that are theoretically equal are not always numerically equal.

template<class TypeT>

void RWUpperTriMat< TypeT >::printOn

(

std::ostream &

os

)

const

Prints the matrix to an output stream in human readable format.

template<class TypeT >

RWRORef< TypeT > RWUpperTriMat< TypeT >::ref ( int  i, int  j  )

inline

Returns a reference to the ij ^th element of the matrix. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined when the header file is read. The member function bcref() does the same thing with guaranteed bounds checking.

template<class TypeT>

RWUpperTriMat<TypeT>& RWUpperTriMat< TypeT >::reference

(

RWUpperTriMat< TypeT > &

m

)

Makes this matrix a reference to the matrix m. The two matrices share the same data. The matrices do not have to be the same size before calling reference(). To copy a matrix into another of the same size, use operator=().

template<class TypeT>

void RWUpperTriMat< TypeT >::resize	(	unsigned	m,
		unsigned	n
	)

Resizes the matrix. Any new entries in the matrix are set to 0. Both arguments must be the same.

template<class TypeT>

void RWUpperTriMat< TypeT >::restoreFrom

(

RWvistream &

is

)

Reads in a matrix from an RWvistream, the Rogue Wave virtual input stream class. The matrix must have been stored to the stream using the saveOn() member function.

template<class TypeT>

void RWUpperTriMat< TypeT >::restoreFrom

(

RWFile &

f

)

Reads in a matrix from an RWFile. The matrix must have been stored to the file using the saveOn() member function.

template<class TypeT>

unsigned RWUpperTriMat< TypeT >::rows ( ) const

inline

Returns the number of rows in the matrix.

template<class TypeT>

void RWUpperTriMat< TypeT >::saveOn

(

RWvostream &

os

)

const

Stores a matrix to an RWvostream, the Rogue Wave virtual output stream class. The matrix can be read using restoreFrom().

template<class TypeT>

void RWUpperTriMat< TypeT >::saveOn

(

RWFile &

f

)

const

Stores a matrix to an RWFile. The matrix can be read using the restoreFrom() member function.

template<class TypeT>

void RWUpperTriMat< TypeT >::scanFrom

(

std::istream &

is

)

Reads a matrix from an input stream. The format of the matrix is the same as the format output by printOn(). Below is a sample matrix that could be input. Note that extra white space and any text preceding the dimension specification are ignored. Only the upper triangle of the matrix is used.

4x4
[
 4    3    3    9
 0    9   -1    5
 0    0    3    1
 0    0    0   -2
]

template<class TypeT >

TypeT RWUpperTriMat< TypeT >::set ( int  i, int  j, TypeT  x  )

inline

Sets the ij ^thelement of the matrix equal to x. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined when the header file is read. The member function bcset() does the same thing with guaranteed bounds checking.

template<class TypeT >

TypeT RWUpperTriMat< TypeT >::val ( int  i, int  j  ) const

inline

Returns the value of the ij ^th element of the matrix. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined when the header file is read. The member function bcval() does the same thing with guaranteed bounds checking.

template<class TypeT>

void RWUpperTriMat< TypeT >::zero ( )

inline

Sets every element of the matrix to 0.

Friends And Related Function Documentation

template<class TypeT >

RWUpperTriMat< typename rw_numeric_traits< TypeT >::norm_type > abs ( const RWUpperTriMat< TypeT > &  A )

related

Returns a matrix whose entries are the absolute value of the argument. The absolute value of a complex number is considered to be the sum of the absolute values of its real and imaginary parts. To get the norm of a complex matrix, you can use the norm() function.

template<class TypeT>

RWUpperTriMat< double > arg ( const RWUpperTriMat< DComplex > &  A )

related

Returns a matrix where each element is the argument of the corresponding element in the matrix A.

template<class TypeT >

RWUpperTriMat< TypeT > conj ( const RWUpperTriMat< TypeT > &  A )

related

Returns a matrix where each element is the complex conjugate of the corresponding element in the matrix A.

template<class TypeT>

RWUpperTriMat< double > imag ( const RWUpperTriMat< DComplex > &  A )

related

Returns a matrix where each element is the imaginary part of the corresponding element in the matrix A.

template<class TypeT>

double maxValue ( const RWUpperTriMat< double > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

float maxValue ( const RWUpperTriMat< float > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

double minValue ( const RWUpperTriMat< double > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

float minValue ( const RWUpperTriMat< float > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

RWUpperTriMat< double > norm ( const RWUpperTriMat< DComplex > &  A )

related

Returns a matrix where each element is the norm (magnitude) of the corresponding element in the matrix A.

template<class TypeT >

RWUpperTriMat< TypeT > operator* ( const RWUpperTriMat< TypeT > &  , const RWUpperTriMat< TypeT > &    )

related

Performs element-by-element operations on the arguments. To do inner product matrix multiplication, you can use the product() global function.

template<class TypeT >

RWUpperTriMat< TypeT > operator* ( const RWUpperTriMat< TypeT > &  A, TypeT  x  )

related

Performs element-by-element multiplication on the arguments.

template<class TypeT >

RWUpperTriMat< TypeT > operator* ( TypeT  x, const RWUpperTriMat< TypeT > &  A  )

related

Performs element-by-element multiplication on the arguments.

template<class TypeT >

RWUpperTriMat< TypeT > operator+ ( const RWUpperTriMat< TypeT > &  m )

related

Unary plus operator. Returns a copy of the matrix m.

template<class TypeT >

RWUpperTriMat< TypeT > operator+ ( const RWUpperTriMat< TypeT > &  , const RWUpperTriMat< TypeT > &    )

related

Performs element-by-element addition on the arguments.

template<class TypeT >

RWUpperTriMat< TypeT > operator- ( const RWUpperTriMat< TypeT > &  m )

related

Unary minus operator. Returns the negation of the matrix m.

template<class TypeT >

RWUpperTriMat< TypeT > operator- ( const RWUpperTriMat< TypeT > &  , const RWUpperTriMat< TypeT > &    )

related

Performs element-by-element subtraction on the arguments.

template<class TypeT >

RWUpperTriMat< TypeT > operator/ ( const RWUpperTriMat< TypeT > &  , const RWUpperTriMat< TypeT > &    )

related

Performs element-by-element division on the arguments.

template<class TypeT >

RWUpperTriMat< TypeT > operator/ ( const RWUpperTriMat< TypeT > &  A, TypeT  x  )

related

Performs element-by-element division on the arguments.

template<class TypeT >

std::ostream & operator<< ( std::ostream &  s, const RWUpperTriMat< TypeT > &  m  )

related

Writes the matrix to the stream. This is equivalent to calling the printOn() member function.

template<class TypeT >

std::istream & operator>> ( std::istream &  s, RWUpperTriMat< TypeT > &  m  )

related

Reads the matrix from the stream. This is equivalent to calling the scanFrom() member function.

template<class TypeT >

RWMathVec< TypeT > product ( const RWUpperTriMat< TypeT > &  A, const RWMathVec< TypeT > &  x  )

related

Returns the inner product (matrix-vector product) of A and x.

template<class TypeT >

RWMathVec< TypeT > product ( const RWMathVec< TypeT > &  x, const RWUpperTriMat< TypeT > &  A  )

related

Returns the inner product (matrix-vector product) of x and A. This is equal to the product of A transpose and x.

template<class TypeT>

RWUpperTriMat< double > real ( const RWUpperTriMat< DComplex > &  A )

related

Returns a matrix where each element is the real part of the corresponding element in the matrix A.

template<class TypeT >

RWUpperTriMat< TypeT > toUpperTriMat ( const RWGenMat< TypeT > &  A )

related

Extracts the upper triangular part of a square matrix.

template<class TypeT >

RWLowerTriMat< TypeT > transpose ( const RWUpperTriMat< TypeT > &  )

related

Returns the transpose of the argument matrix. The transpose is made to reference the same data as the argument matrix.