RWSymBandMat< TypeT > Class Template Reference

Encapsulates a symmetric band matrix. More...

#include <rw/lapack/sbndmat.h>

Public Member Functions
	RWSymBandMat ()
	RWSymBandMat (const RWSymBandMat< TypeT > &A)
	RWSymBandMat (unsigned n, unsigned nAgain, unsigned hb)
	RWSymBandMat (const RWMathVec< TypeT > &data, unsigned n, unsigned nAgain, unsigned hb)
	RWSymBandMat (const RWSymBandMat< double > &re, const RWSymBandMat< double > &im)
unsigned	bandwidth () const
RWMathVec< TypeT >	bcdiagonal (int j=0) const
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
RWSymBandMat< TypeT >	copy () const
TypeT *	data ()
RWMathVec< TypeT >	dataVec ()
RWSymBandMat< TypeT >	deepCopy () const
void	deepenShallowCopy ()
RWMathVec< TypeT >	diagonal (int j=0) const
unsigned	halfBandwidth () const
RWSymBandMat< TypeT >	leadingSubmatrix (int k)
unsigned	lowerBandwidth () const
bool	operator!= (const RWSymBandMat< TypeT > &X)
RWRORef< TypeT >	operator() (int i, int j)
TypeT	operator() (int i, int j) const
RWSymBandMat< TypeT > &	operator*= (const RWSymBandMat< TypeT > &m)
RWSymBandMat< TypeT > &	operator*= (TypeT)
RWSymBandMat< TypeT > &	operator+= (const RWSymBandMat< TypeT > &m)
RWSymBandMat< TypeT > &	operator-= (const RWSymBandMat< TypeT > &m)
RWSymBandMat< TypeT > &	operator/= (const RWSymBandMat< TypeT > &m)
RWSymBandMat< TypeT > &	operator/= (TypeT)
RWSymBandMat< TypeT > &	operator= (const RWSymBandMat< TypeT > &A)
bool	operator== (const RWSymBandMat< TypeT > &X)
void	printOn (std::ostream &) const
RWRORef< TypeT >	ref (int i, int j)
RWSymBandMat< TypeT > &	reference (RWSymBandMat< TypeT > &m)
void	resize (unsigned m, unsigned n)
void	resize (unsigned n, unsigned nAgain, unsigned halfWidth)
void	restoreFrom (RWvistream &)
void	restoreFrom (RWFile &)
unsigned	rows () const
void	saveOn (RWvostream &) const
void	saveOn (RWFile &) const
void	scanFrom (std::istream &)
TypeT	set (int i, int j, TypeT x)
unsigned	upperBandwidth () const
TypeT	val (int i, int j) const
void	zero ()

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

Detailed Description

template<class TypeT>
class RWSymBandMat< TypeT >

The class RWSymBandMat encapsulates symmetric band matrices. A symmetric banded matrix is symmetric, and nonzero only near the diagonal. Specifically, if h is the half bandwidth, then any entries for which \(i-j > h\) or \(j-i > h\) are defined to be 0; in addition, an entry \(A_{ij} = A_{ji}\).

Synopsis

#include <rw/lapack/sbndmat.h>

RWSymBandMat<double> d;

Example

#include <rw/lapack/sbndmat.h>

int main()
{
    RWSymBandMat<float> SB(4,4,1);
    SB.diagonal(-1) = -1;
    SB.diagonal( ) = 0;
    SB.diagonal( 1) = 1;
}

Storage Scheme

As an example of the storage scheme, consider the following 9 x 9 matrix with a half bandwidth of two:

\[ \begin{bmatrix} & A_{11} & A_{12} & A_{13} & 0 & 0 & 0 & 0 & 0 & 0 \\ & A_{12} & A_{22} & A_{23} & A_{24} & 0 & 0 & 0 & 0 & 0 \\ & A_{13} & A_{23} & A_{33} & A_{34} & A_{35} & 0 & 0 & 0 & 0 \\ & 0 & A_{24} & A_{34} & A_{44} & A_{45} & A_{46} & 0 & 0 & 0 \\ & 0 & 0 & A_{35} & A_{45} & A_{55} & A_{56} & A_{57} & 0 & 0 \\ & 0 & 0 & 0 & A_{46} & A_{56} & A_{66} & A_{67} & A_{68} & 0 \\ & 0 & 0 & 0 & 0 & A_{57} & A_{67} & A_{77} & A_{78} & A_{79} \\ & 0 & 0 & 0 & 0 & 0 & A_{68} & A_{78} & A_{88} & A_{89} \\ & 0 & 0 & 0 & 0 & 0 & 0 & A_{79} & A_{89} & A_{99} \\ \end{bmatrix} \]

The upper triangle is stored column by column. For convenience, there are some unused locations left in the vector of data. These are indicated as XXX in the following illustration of the storage vector:

[ XXX XXX A11
  XXX A12 A22
  A13 A23 A33
  A24 A34 A44
  A35 A45 A55
  A46 A56 A66
  A57 A67 A77
  A68 A78 A88
  A79 A89 A99 ]

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

\[ A(i + 1, j + 1) \to \left\{ \begin{array}{l l} \text{vec}[i + \text{halfwidth} + j*\text{halfwidth}] & \quad \text{if } j \geq i \\ \text{vec}[j + \text{halfwidth} + i*\text{halfwidth}] & \quad \text{if } j < i \\ \end{array} \right. \]

Constructor & Destructor Documentation

template<class TypeT>

RWSymBandMat< TypeT >::RWSymBandMat

(

)

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>

RWSymBandMat< TypeT >::RWSymBandMat

(

const RWSymBandMat< TypeT > &

A

)

Build a copy of its argument, A. Note that the new matrix references A's data. To construct a matrix with its own copy of the data, you can use either the copy() or deepenShallowCopy() member functions.

template<class TypeT>

RWSymBandMat< TypeT >::RWSymBandMat	(	unsigned	n,
		unsigned	nAgain,
		unsigned	hb
	)

Defines an uninitialized matrix of size n x nAgain with half bandwidth hb.

template<class TypeT>

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

Constructs an n x nAgain matrix with half bandwidth hb 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.

template<class TypeT>

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

Constructs a complex matrix from the real and imaginary parts supplied. If no imaginary part is supplied, it is assumed to be 0.

Member Function Documentation

template<class TypeT>

unsigned RWSymBandMat< TypeT >::bandwidth ( ) const

inline

Returns the bandwidth of the matrix. The bandwidth is twice the half bandwidth plus 1 for the main diagonal.

template<class TypeT>

RWMathVec<TypeT> RWSymBandMat< TypeT >::bcdiagonal

(

int

j = 0

)

const

Returns a reference to the j ^th diagonal of the matrix, after doing bounds checking. The main diagonal is indexed by 0, diagonals in the upper triangle are indexed with positive integers, diagonals in the lower triangle are indexed with negative integers.

template<class TypeT>

RWRORef<TypeT> RWSymBandMat< 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 RWSymBandMat< 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 RWSymBandMat< 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 RWSymBandMat< 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 RWSymBandMat< TypeT >::cols ( ) const

inline

Returns the number of columns in the matrix.

template<class TypeT>

RWSymBandMat<TypeT> RWSymBandMat< 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* RWSymBandMat< 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>

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

inline

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

template<class TypeT>

RWSymBandMat<TypeT> RWSymBandMat< 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 RWSymBandMat< TypeT >::deepenShallowCopy ( )

inline

Ensures that the data in the matrix is not shared by any other matrix or vector. Also ensure 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 >

RWMathVec< TypeT > RWSymBandMat< TypeT >::diagonal ( int  j = 0 ) const

inline

Returns a reference to the j ^th diagonal of the matrix. The main diagonal is indexed by 0, diagonals in the upper triangle are indexed with positive integers, and diagonals in the lower triangle are indexed with negative integers. Bounds checking is done if the preprocessor symbol RWBOUNDS_CHECK is defined when the header file is read. The member function bcdiagonal() does the same thing with guaranteed bounds checking.

template<class TypeT>

unsigned RWSymBandMat< TypeT >::halfBandwidth ( ) const

inline

Returns the half bandwidth of the matrix.

template<class TypeT>

RWSymBandMat<TypeT> RWSymBandMat< 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>

unsigned RWSymBandMat< TypeT >::lowerBandwidth ( ) const

inline

Returns the lower bandwidth of the matrix.

template<class TypeT>

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

inline

Two matrices are considered equal if they have the same size and their elements are all exactly the same. Be aware that floating point arithmetic is not exact; matrices that are theoretically equal are not always numerically equal.

template<class TypeT >

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

inline

Returns a reference to the ij ^th element of the matrix. 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 RWSymBandMat< TypeT >::operator() ( int  i, int  j  ) const

inline

Accesses the ij ^th 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>

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

(

const RWSymBandMat< TypeT > &

m

)

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

Note

For matrix-matrix inner product multiplication, use the product() global function.

template<class TypeT>

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

(

TypeT

)

Performs the indicated operation on each element of the matrix.

template<class TypeT>

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

(

const RWSymBandMat< TypeT > &

m

)

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

template<class TypeT>

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

(

const RWSymBandMat< TypeT > &

m

)

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

template<class TypeT>

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

(

const RWSymBandMat< TypeT > &

m

)

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

template<class TypeT>

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

(

TypeT

)

Performs the indicated operation on each element of the matrix.

template<class TypeT>

RWSymBandMat<TypeT>& RWSymBandMat< TypeT >::operator=

(

const RWSymBandMat< 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 the reference() member function.

template<class TypeT>

bool RWSymBandMat< TypeT >::operator==

(

const RWSymBandMat< TypeT > &

X

)

Two matrices are considered equal if they have the same size and their elements are all exactly the same. Be aware that floating point arithmetic is not exact; matrices that are theoretically equal are not always numerically equal.

template<class TypeT>

void RWSymBandMat< TypeT >::printOn

(

std::ostream &

)

const

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

template<class TypeT >

RWRORef< TypeT > RWSymBandMat< 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>

RWSymBandMat<TypeT>& RWSymBandMat< TypeT >::reference

(

RWSymBandMat< TypeT > &

m

)

Makes this matrix a reference to the argument matrix. 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 the operator=() member operator.

template<class TypeT>

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

Resizes the matrix or changes both its size and half bandwidth. Any new entries in the matrix are set to 0. Both arguments must be the same.

template<class TypeT>

void RWSymBandMat< TypeT >::resize	(	unsigned	n,
		unsigned	nAgain,
		unsigned	halfWidth
	)

Resizes the matrix or changes both its size and half bandwidth. Any new entries in the matrix are set to 0. Both arguments must be the same.

template<class TypeT>

void RWSymBandMat< TypeT >::restoreFrom

(

RWvistream &

)

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 RWSymBandMat< TypeT >::restoreFrom

(

RWFile &

)

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 RWSymBandMat< TypeT >::rows ( ) const

inline

Returns the number of rows in the matrix.

template<class TypeT>

void RWSymBandMat< TypeT >::saveOn

(

RWvostream &

)

const

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

template<class TypeT>

void RWSymBandMat< TypeT >::saveOn

(

RWFile &

)

const

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

template<class TypeT>

void RWSymBandMat< TypeT >::scanFrom

(

std::istream &

)

Reads a matrix from an input stream. The format of the matrix is the same as the format output by the printOn() member function: first the half bandwidth, followed by the matrix itself. Below is a sample matrix showing the format. Note that extra white space and text preceding the bandwidth specification are ignored. Only the symmetric part of the relevant band of the matrix is used.

1  5x5
[
  3  7  0  0  0
  7  2  2  0  0
  0  2  8  9  0
  0  0  9  8  7
  0  0  0  7  8
]

template<class TypeT >

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

inline

Sets the ij ^th element 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>

unsigned RWSymBandMat< TypeT >::upperBandwidth ( ) const

inline

Returns the upper bandwidth of the matrix.

template<class TypeT >

TypeT RWSymBandMat< 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 RWSymBandMat< TypeT >::zero ( )

inline

Sets every element of the matrix to 0.

Friends And Related Function Documentation

template<class TypeT >

RWSymBandMat< typename rw_numeric_traits< TypeT >::norm_type > abs ( const RWSymBandMat< 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>

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

related

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

template<class TypeT>

RWSymBandMat< DComplex > conj ( const RWSymBandMat< DComplex > &  A )

related

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

template<class TypeT>

RWSymBandMat< double > imag ( const RWSymBandMat< 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 RWSymBandMat< double > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

float maxValue ( const RWSymBandMat< float > &  A )

related

Returns the maximum entry in the matrix.

template<class TypeT>

double minValue ( const RWSymBandMat< double > &  A )

related

Returns the minimum entry in the matrix.

template<class TypeT>

float minValue ( const RWSymBandMat< float > &  A )

related

Returns the minimum entry in the matrix.

template<class TypeT>

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

related

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

template<class TypeT >

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

related

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

template<class TypeT >

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

related

Performs element-by-element operations on the arguments.

template<class TypeT >

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

related

Performs element-by-element operations on the arguments.

template<class TypeT >

RWSymBandMat< TypeT > operator+ ( const RWSymBandMat< TypeT > &  )

related

Unary plus operator. Returns a copy of the matrix.

template<class TypeT >

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

related

Performs element-by-element operation on the arguments.

template<class TypeT >

RWSymBandMat< TypeT > operator- ( const RWSymBandMat< TypeT > &  )

related

Unary minus operator. Returns a copy of matrix's negation.

template<class TypeT >

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

related

Performs element-by-element operation on the arguments.

template<class TypeT >

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

related

Performs element-by-element operation on the arguments.

template<class TypeT >

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

related

Performs element-by-element operations on the arguments.

template<class TypeT >

std::ostream & operator<< ( std::ostream &  s, const RWSymBandMat< 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, RWSymBandMat< 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 RWSymBandMat< 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 RWSymBandMat< 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>

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

related

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

template<class TypeT >

RWSymBandMat< TypeT > toSymBandMat ( const RWBandMat< TypeT > &  A )

related

Extracts the symmetric part of a banded matrix. The symmetric part of the banded matrix A is \((A + A^{T})/2\).

template<class TypeT >

RWSymBandMat< TypeT > transpose ( const RWSymBandMat< TypeT > &  )

related

Returns the transpose of the argument matrix.