rwlogo
SourcePro C++ 12.0

SourcePro® C++ API Reference Guide

   SourcePro C++
Documentation Home

RWHermBandMat< TypeT > Class Template Reference
[Sparse Matrices]

Encapsulates a Hermitian banded matrix. A Hermitian banded matrix is Hermitian, and nonzero only near the diagonal. More...

#include <rw/lapack/hbndmat.h>

List of all members.

Public Member Functions

 RWHermBandMat ()
 RWHermBandMat (const RWHermBandMat< TypeT > &A)
 RWHermBandMat (unsigned x, unsigned y, unsigned hb)
 RWHermBandMat (const RWMathVec< TypeT > &vd, unsigned x, unsigned y, unsigned hb)
 RWHermBandMat (const RWSymBandMat< double > &re)
unsigned rows () const
unsigned cols () const
unsigned bandwidth () const
unsigned halfBandwidth () const
unsigned lowerBandwidth () const
unsigned upperBandwidth () const
TypeT val (int i, int j) const
TypeT set (int i, int j, TypeT x)
RWROCJRef< TypeT > ref (int i, int j)
TypeT bcval (int i, int j) const
TypeT bcset (int i, int j, TypeT x)
RWROCJRef< TypeT > bcref (int i, int j)
RWHermBandMat< TypeT > leadingSubmatrix (int k)
RWHermBandMat< TypeT > & reference (RWHermBandMat< TypeT > &m)
void zero ()
RWHermBandMat copy () const
RWHermBandMat deepCopy () const
void deepenShallowCopy ()
RWMathVec< TypeT > dataVec ()
TypeT * data ()
void resize (unsigned m, unsigned n)
void resize (unsigned n, unsigned nAgain, unsigned halfWidth)
void makeDiagonalReal ()
void scanFrom (std::istream &)
void printOn (std::ostream &) const
void restoreFrom (RWvistream &)
void saveOn (RWvostream &) const
void restoreFrom (RWFile &)
void saveOn (RWFile &) const
unsigned binaryStoreSize () const
RWROCJRef< TypeT > operator() (int i, int j)
TypeT operator() (int i, int j) const
bool operator== (const RWHermBandMat< TypeT > &X)
bool operator!= (const RWHermBandMat< TypeT > &X)
RWHermBandMat< TypeT > & operator= (const RWHermBandMat< TypeT > &A)
RWHermBandMat< TypeT > & operator+= (const RWHermBandMat< TypeT > &m)
RWHermBandMat< TypeT > & operator-= (const RWHermBandMat< TypeT > &m)
RWHermBandMat< TypeT > & operator*= (const RWHermBandMat< TypeT > &m)
RWHermBandMat< TypeT > & operator*= (TypeT)
RWHermBandMat< TypeT > & operator/= (const RWHermBandMat< TypeT > &m)
RWHermBandMat< TypeT > & operator/= (TypeT)

Related Functions

(Note that these are not member functions.)



template<class TypeT >
RWHermBandMat< TypeT > operator- (const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator+ (const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator* (const RWHermBandMat< TypeT > &, const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator/ (const RWHermBandMat< TypeT > &, const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator+ (const RWHermBandMat< TypeT > &, const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator- (const RWHermBandMat< TypeT > &, const RWHermBandMat< TypeT > &)
template<class TypeT >
RWHermBandMat< TypeT > operator* (const RWHermBandMat< TypeT > &A, TypeT x)
template<class TypeT >
RWHermBandMat< TypeT > operator* (TypeT x, const RWHermBandMat< TypeT > &A)
template<class TypeT >
RWHermBandMat< TypeT > operator/ (const RWHermBandMat< TypeT > &A, TypeT x)
template<class TypeT >
std::ostream & operator<< (std::ostream &s, const RWHermBandMat< TypeT > &m)
template<class TypeT >
std::istream & operator>> (std::istream &s, RWHermBandMat< TypeT > &m)
template<class TypeT >
RWHermBandMat< TypeT > transpose (const RWHermBandMat< TypeT > &)
template<class TypeT >
RWMathVec< TypeT > product (const RWHermBandMat< TypeT > &A, const RWMathVec< TypeT > &x)
template<class TypeT >
RWMathVec< TypeT > product (const RWMathVec< TypeT > &x, const RWHermBandMat< TypeT > &A)
template<class TypeT >
RWHermBandMat< TypeT > toHermBandMat (const RWGenMat< TypeT > &A, unsigned h)
template<class TypeT >
RWSymBandMat< double > abs (const RWHermBandMat< TypeT > &A)
template<class TypeT >
RWHermBandMat< TypeT > conj (const RWHermBandMat< TypeT > &A)
template<class TypeT >
RWSymBandMat< double > real (const RWHermBandMat< TypeT > &A)
template<class TypeT >
RWSymBandMat< double > norm (const RWHermBandMat< TypeT > &A)

Detailed Description

template<class TypeT>
class RWHermBandMat< TypeT >

The class RWHermBandMat<T> encapsulates a Hermitian banded matrix. A Hermitian banded matrix is Hermitian, 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 Aij = conj(Aji). Although this strict definition implies a matrix with 0 imaginary parts along the diagonal, the Rogue Wave class implementation allows arbitrary diagonal entries.

Synopsis

 #include <rw/lapack/hbndmat.h>
 
 RWHermBandMat<DComplex> H;

Example

 #include <rw/lapack/hbndmat.h>
 
 int main()
 {
     RWHermBandMat<DComplex> HB(5,5,1);
     HB.zero();
     HB.set(2, 2, DComplex(2,1));
 }

Storage Scheme

As an example of the storage scheme for banded Hermitian matrices, consider the following 9x9 matrix with a half bandwidth of 2, where entries aij are notation for conj(Aij):

\[ \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 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 the storage vector is as follows:

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

Constructor & Destructor Documentation

template<class TypeT>
RWHermBandMat< TypeT >::RWHermBandMat (  ) 

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

template<class TypeT>
RWHermBandMat< TypeT >::RWHermBandMat ( const RWHermBandMat< TypeT > &  A  ) 

Builds 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, use either the copy() or deepenShallowCopy() member functions.

template<class TypeT>
RWHermBandMat< TypeT >::RWHermBandMat ( unsigned  x,
unsigned  y,
unsigned  hb 
)

Defines an uninitialized x by y matrix with half bandwidth hb.

template<class TypeT>
RWHermBandMat< TypeT >::RWHermBandMat ( const RWMathVec< TypeT > &  vd,
unsigned  x,
unsigned  y,
unsigned  hb 
)

Constructs a x by y 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 vd.

template<class TypeT>
RWHermBandMat< TypeT >::RWHermBandMat ( const RWSymBandMat< double > &  re  ) 

Converts a real matrix to a Hermitian banded matrix.

Member Function Documentation

template<class TypeT>
unsigned RWHermBandMat< TypeT >::bandwidth (  )  const [inline]

Returns the bandwidth of the matrix.

template<class TypeT>
RWROCJRef<TypeT> RWHermBandMat< 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 RWHermBandMat< 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 RWHermBandMat< 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 RWHermBandMat< 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 RWHermBandMat< TypeT >::cols (  )  const [inline]

Returns the number of columns in the matrix.

template<class TypeT>
RWHermBandMat RWHermBandMat< 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* RWHermBandMat< 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 to pass the matrix's data to C or FORTRAN subroutines, but be aware that the stride of the data vector may not be 1.

template<class TypeT>
RWMathVec<TypeT> RWHermBandMat< TypeT >::dataVec (  )  [inline]

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

template<class TypeT>
RWHermBandMat RWHermBandMat< 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 RWHermBandMat< 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>
unsigned RWHermBandMat< TypeT >::halfBandwidth (  )  const [inline]

Returns the half bandwidth of the matrix.

template<class TypeT>
RWHermBandMat<TypeT> RWHermBandMat< 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 RWHermBandMat< TypeT >::lowerBandwidth (  )  const [inline]

Returns the lower bandwidth of the matrix.

template<class TypeT>
void RWHermBandMat< TypeT >::makeDiagonalReal (  ) 

Sets the imaginary part of the main diagonal to 0, thus ensuring that the matrix satisfies the strict mathematical definition of Hermitian.

template<class TypeT>
bool RWHermBandMat< TypeT >::operator!= ( const RWHermBandMat< TypeT > &  X  )  [inline]

Boolean operators. 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 which are theoretically equal are not always numerically equal.

template<class TypeT >
TypeT RWHermBandMat< 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 >
RWROCJRef< TypeT > RWHermBandMat< 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>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator*= ( TypeT   ) 

Performs the indicated operation on each element of the matrix.

template<class TypeT>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator*= ( const RWHermBandMat< 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>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator+= ( const RWHermBandMat< TypeT > &  m  ) 

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

template<class TypeT>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator-= ( const RWHermBandMat< TypeT > &  m  ) 

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

template<class TypeT>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator/= ( TypeT   ) 

Performs the indicated operation on each element of the matrix.

template<class TypeT>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator/= ( const RWHermBandMat< TypeT > &  m  ) 

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

template<class TypeT>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::operator= ( const RWHermBandMat< 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, you can use the reference member function.

template<class TypeT>
bool RWHermBandMat< TypeT >::operator== ( const RWHermBandMat< TypeT > &  X  ) 

Boolean operators. 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 which are theoretically equal are not always numerically equal.

template<class TypeT>
void RWHermBandMat< TypeT >::printOn ( std::ostream &   )  const

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

template<class TypeT >
RWROCJRef< TypeT > RWHermBandMat< 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>
RWHermBandMat<TypeT>& RWHermBandMat< TypeT >::reference ( RWHermBandMat< 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 RWHermBandMat< TypeT >::resize ( unsigned  n,
unsigned  nAgain,
unsigned  halfWidth 
)

Resizes the matrix or changes both the size of the matrix and the bandwidth. Any new entries in the matrix are set to 0.

template<class TypeT>
void RWHermBandMat< TypeT >::resize ( unsigned  m,
unsigned  n 
)

Resizes the matrix or changes both the size of the matrix and the bandwidth. Any new entries in the matrix are set to 0.

template<class TypeT>
void RWHermBandMat< 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>
void RWHermBandMat< 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>
unsigned RWHermBandMat< TypeT >::rows (  )  const [inline]

Returns the number of rows in the matrix.

template<class TypeT>
void RWHermBandMat< TypeT >::saveOn ( RWFile &   )  const

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

template<class TypeT>
void RWHermBandMat< 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 RWHermBandMat< 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 Hermitian part of the relevant band of the matrix is used.

 1  5x5
 [ (3,0)  (7,1) (0,0)  (0,0)  (0,0)
   (7,-1) (2,0) (2,-3) (0,0)  (0,0)
   (0,0)  (2,3) (8,0)  (9,-5) (0,0)
   (0,0)  (0,0) (9,5)  (8,0)  (7,1)
   (0,0)  (0,0) (0,0)  (7,-1) (8,0) ]
template<class TypeT >
TypeT RWHermBandMat< 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 RWHermBandMat< TypeT >::upperBandwidth (  )  const [inline]

Returns the upper bandwidth of the matrix.

template<class TypeT >
TypeT RWHermBandMat< 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 RWHermBandMat< TypeT >::zero (  )  [inline]

Sets every element of the matrix to 0.

Friends And Related Function Documentation

template<class TypeT >
RWSymBandMat< double > abs ( const RWHermBandMat< 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 >
RWHermBandMat< TypeT > conj ( const RWHermBandMat< TypeT > &  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 > norm ( const RWHermBandMat< TypeT > &  A  )  [related]

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

template<class TypeT >
RWHermBandMat< TypeT > operator* ( TypeT  x,
const RWHermBandMat< TypeT > &  A 
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
RWHermBandMat< TypeT > operator* ( const RWHermBandMat< TypeT > &  A,
TypeT  x 
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
RWHermBandMat< TypeT > operator* ( const RWHermBandMat< TypeT > &  ,
const RWHermBandMat< 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 >
RWHermBandMat< TypeT > operator+ ( const RWHermBandMat< TypeT > &  ,
const RWHermBandMat< TypeT > &   
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
RWHermBandMat< TypeT > operator+ ( const RWHermBandMat< TypeT > &   )  [related]

Unary plus operator. Returns a copy of the matrix.

template<class TypeT >
RWHermBandMat< TypeT > operator- ( const RWHermBandMat< TypeT > &  ,
const RWHermBandMat< TypeT > &   
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
RWHermBandMat< TypeT > operator- ( const RWHermBandMat< TypeT > &   )  [related]

Unary minus operator. Returns a copy of the matrix.

template<class TypeT >
RWHermBandMat< TypeT > operator/ ( const RWHermBandMat< TypeT > &  A,
TypeT  x 
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
RWHermBandMat< TypeT > operator/ ( const RWHermBandMat< TypeT > &  ,
const RWHermBandMat< TypeT > &   
) [related]

Performs element-by-element operations on the arguments.

template<class TypeT >
std::ostream & operator<< ( std::ostream &  s,
const RWHermBandMat< 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,
RWHermBandMat< 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 RWMathVec< TypeT > &  x,
const RWHermBandMat< 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 >
RWMathVec< TypeT > product ( const RWHermBandMat< TypeT > &  A,
const RWMathVec< TypeT > &  x 
) [related]

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

template<class TypeT >
RWSymBandMat< double > real ( const RWHermBandMat< TypeT > &  A  )  [related]

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

template<class TypeT >
RWHermBandMat< TypeT > toHermBandMat ( const RWGenMat< TypeT > &  A,
unsigned  h 
) [related]

Extracts the Hermitian part of a band of entries from a square matrix. The main diagonal is extracted, along with h subdiagonals and superdiagonals. If B is this band, the Hermitian part of the band is $ (B+conj(B_{T}))/2 $.

template<class TypeT >
RWHermBandMat< TypeT > transpose ( const RWHermBandMat< TypeT > &   )  [related]

Returns the transpose of the argument matrix.

 All Classes Functions Variables Typedefs Enumerations Enumerator Friends

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.