A class for banded matrices, involving matrix inversion processes. More...

#include <BandMatrix.h>

Inheritance diagram for BandMatrix:

Detailed Description

A class for banded matrices, involving matrix inversion processes.

The class is based upon the LAPACK banded storage matrix format.

An important issue with this class is that it stores both the original data and the LU factorization of the data. This means that the banded matrix typically will take up twice the room that it is expected to take.

QR factorizations of banded matrices are not included in the original LAPACK work. Add-ons are available. However, they are not included here. Instead we just use the stock LU decompositions.

This class is a derived class of the base class GeneralMatrix. However, within the oneD directory, the class is used as is, without reference to the GeneralMatrix base type.

Definition at line 36 of file BandMatrix.h.

Classes
struct	PivData

Public Member Functions
	BandMatrix ()
	Base Constructor.

	BandMatrix (size_t n, size_t kl, size_t ku, double v=0.0)
	Creates a banded matrix and sets all elements to zero.

	BandMatrix (const BandMatrix &y)

BandMatrix &	operator= (const BandMatrix &y)

void	resize (size_t n, size_t kl, size_t ku, double v=0.0)
	Resize the matrix problem.

void	bfill (double v=0.0)
	Fill or zero the matrix.

double &	operator() (size_t i, size_t j) override
	Index into the (i,j) element.

double	operator() (size_t i, size_t j) const override
	Constant Index into the (i,j) element.

double &	value (size_t i, size_t j)
	Return a changeable reference to element (i,j).

double	value (size_t i, size_t j) const
	Return the value of element (i,j).

size_t	index (size_t i, size_t j) const
	Returns the location in the internal 1D array corresponding to the (i,j) element in the banded array.

double	_value (size_t i, size_t j) const
	Return the value of the (i,j) element for (i,j) within the bandwidth.

size_t	nRows () const override
	Return the number of rows in the matrix.

size_t	nColumns () const
	Number of columns.

size_t	nSubDiagonals () const
	Number of subdiagonals.

size_t	nSuperDiagonals () const
	Number of superdiagonals.

size_t	ldim () const
	Return the number of rows of storage needed for the band storage.

void	mult (span< const double > b, span< double > prod) const override
	Multiply A*b and write result to `prod`.

void	leftMult (span< const double > b, span< double > prod) const override
	Multiply b*A and write result to prod.

void	factor () override
	Perform an LU decomposition, the LAPACK routine DGBTRF is used.

void	solve (span< const double > b, span< double > x)
	Solve the matrix problem Ax = b.

void	solve (span< double > b, size_t nrhs=1, size_t ldb=0) override
	Solve the matrix problem Ax = b.

void	zero () override
	Zero the matrix elements.

double	rcond (double a1norm) override
	Returns an estimate of the inverse of the condition number for the matrix.

int	factorAlgorithm () const override
	Returns the factor algorithm used.

double	oneNorm () const override
	Returns the one norm of the matrix.

size_t	checkRows (double &valueSmall) const override
	Check to see if we have any zero rows in the Jacobian.

size_t	checkColumns (double &valueSmall) const override
	Check to see if we have any zero columns in the Jacobian.

int	info () const
	LAPACK "info" flag after last factor/solve operation.

Public Member Functions inherited from GeneralMatrix
	GeneralMatrix ()=default
	Base Constructor.

virtual void	zero ()=0
	Zero the matrix elements.

virtual void	mult (span< const double > b, span< double > prod) const =0
	Multiply A*b and write result to prod.

virtual void	leftMult (span< const double > b, span< double > prod) const =0
	Multiply b*A and write result to prod.

virtual void	factor ()=0
	Factors the A matrix, overwriting A.

virtual int	factorQR ()
	Factors the A matrix using the QR algorithm, overwriting A.

virtual double	rcondQR ()
	Returns an estimate of the inverse of the condition number for the matrix.

virtual double	rcond (double a1norm)=0
	Returns an estimate of the inverse of the condition number for the matrix.

virtual void	useFactorAlgorithm (int fAlgorithm)
	Change the way the matrix is factored.

virtual int	factorAlgorithm () const =0
	Return the factor algorithm used.

virtual double	oneNorm () const =0
	Calculate the one norm of the matrix.

virtual size_t	nRows () const =0
	Return the number of rows in the matrix.

virtual void	clearFactorFlag ()
	clear the factored flag

virtual void	solve (span< double > b, size_t nrhs=1, size_t ldb=0)=0
	Solves the Ax = b system returning x in the b spot.

virtual bool	factored () const
	true if the current factorization is up to date with the matrix

virtual span< double >	col (size_t j)
	Return a writable span over column `j`.

virtual span< const double >	col (size_t j) const
	Return a read-only span over column `j`.

virtual double &	operator() (size_t i, size_t j)=0
	Index into the (i,j) element.

virtual double	operator() (size_t i, size_t j) const =0
	Constant Index into the (i,j) element.

virtual size_t	checkRows (double &valueSmall) const =0
	Check to see if we have any zero rows in the Jacobian.

virtual size_t	checkColumns (double &valueSmall) const =0
	Check to see if we have any zero columns in the Jacobian.

Protected Attributes
vector< double >	data
	Matrix data.

vector< double >	ludata
	Factorized data.

vector< double * >	m_lu_col_ptrs
	Pointers into ludata used by the SUNDIALS solver.

size_t	m_n = 0
	Number of rows and columns of the matrix.

size_t	m_kl = 0
	Number of subdiagonals of the matrix.

size_t	m_ku = 0
	Number of super diagonals of the matrix.

double	m_zero = 0
	value of zero

unique_ptr< PivData >	m_ipiv
	Pivot vector.

vector< int >	iwork_
	Extra work array needed - size = n.

vector< double >	work_
	Extra dp work array needed - size = 3n.

int	m_info = 0

Protected Attributes inherited from GeneralMatrix
int	m_factored = false
	Indicates whether the matrix is factored.

Constructor & Destructor Documentation

◆ BandMatrix() [1/3]

BandMatrix ( )

Base Constructor.

Create an 0 by 0 matrix, and initialize all elements to 0.

Definition at line 34 of file BandMatrix.cpp.

◆ ~BandMatrix()

~BandMatrix ( )

Definition at line 39 of file BandMatrix.cpp.

◆ BandMatrix() [2/3]

BandMatrix	(	size_t	n,
		size_t	kl,
		size_t	ku,
		double	v = `0.0`
	)

Creates a banded matrix and sets all elements to zero.

Create an n by n banded matrix, and initialize all elements to v.

Parameters

n	size of the square matrix
kl	band size on the lower portion of the matrix
ku	band size on the upper portion of the matrix
v	initial value of all matrix components.

Definition at line 44 of file BandMatrix.cpp.

◆ BandMatrix() [3/3]

BandMatrix ( const BandMatrix & y )

Definition at line 62 of file BandMatrix.cpp.

Member Function Documentation

◆ operator=()

BandMatrix & operator= ( const BandMatrix & y )

Definition at line 80 of file BandMatrix.cpp.

◆ resize()

void resize	(	size_t	n,
		size_t	kl,
		size_t	ku,
		double	v = `0.0`
	)

Resize the matrix problem.

All data is lost

Parameters

n	size of the square matrix
kl	band size on the lower portion of the matrix
ku	band size on the upper portion of the matrix
v	initial value of all matrix components.

Definition at line 101 of file BandMatrix.cpp.

◆ bfill()

void bfill ( double v = 0.0 )

Fill or zero the matrix.

Parameters

v	Fill value, defaults to zero.

Definition at line 118 of file BandMatrix.cpp.

◆ operator()() [1/2]

double & operator()	(	size_t	i,
		size_t	j
	)

overridevirtual

Index into the (i,j) element.

Parameters

i	row
j	column

Returns: a changeable reference to the matrix entry

Implements GeneralMatrix.

Definition at line 130 of file BandMatrix.cpp.

◆ operator()() [2/2]

double operator()	(	size_t	i,
		size_t	j
	)		const

overridevirtual

Constant Index into the (i,j) element.

Parameters

i	row
j	column

Returns: an unchangeable reference to the matrix entry

Implements GeneralMatrix.

Definition at line 135 of file BandMatrix.cpp.

◆ value() [1/2]

double & value	(	size_t	i,
		size_t	j
	)

Return a changeable reference to element (i,j).

Since this method may alter the element value, it may need to be refactored, so the flag m_factored is set to false.

Parameters

i	row
j	column

Returns: a reference to the value of the matrix entry

Definition at line 140 of file BandMatrix.cpp.

◆ value() [2/2]

double value	(	size_t	i,
		size_t	j
	)		const

Return the value of element (i,j).

This method does not alter the array.

Parameters

i	row
j	column

Returns: the value of the matrix entry

Definition at line 149 of file BandMatrix.cpp.

◆ index()

size_t index	(	size_t	i,
		size_t	j
	)		const

Returns the location in the internal 1D array corresponding to the (i,j) element in the banded array.

Parameters

i	row
j	column

Returns: the index of the matrix entry

Definition at line 157 of file BandMatrix.cpp.

◆ _value()

double _value	(	size_t	i,
		size_t	j
	)		const

Return the value of the (i,j) element for (i,j) within the bandwidth.

For efficiency, this method does not check that (i,j) are within the bandwidth; it is up to the calling program to insure that this is true.

Parameters

i	row
j	column

Returns: the value of the matrix entry

Definition at line 162 of file BandMatrix.cpp.

◆ nRows()

size_t nRows ( ) const

overridevirtual

Return the number of rows in the matrix.

Implements GeneralMatrix.

Definition at line 167 of file BandMatrix.cpp.

◆ nColumns()

size_t nColumns ( ) const

Number of columns.

Definition at line 172 of file BandMatrix.cpp.

◆ nSubDiagonals()

size_t nSubDiagonals ( ) const

Number of subdiagonals.

Definition at line 177 of file BandMatrix.cpp.

◆ nSuperDiagonals()

size_t nSuperDiagonals ( ) const

Number of superdiagonals.

Definition at line 182 of file BandMatrix.cpp.

◆ ldim()

size_t ldim ( ) const

Return the number of rows of storage needed for the band storage.

Definition at line 187 of file BandMatrix.cpp.

◆ mult()

void mult	(	span< const double >	b,
		span< double >	prod
	)		const

overridevirtual

Multiply A*b and write result to prod.

Implements GeneralMatrix.

Definition at line 192 of file BandMatrix.cpp.

◆ leftMult()

void leftMult	(	span< const double >	b,
		span< double >	prod
	)		const

overridevirtual

Multiply b*A and write result to prod.

Parameters

b	Vector to do the lh multiplication
prod	OUTPUT vector to receive the result

Implements GeneralMatrix.

Definition at line 207 of file BandMatrix.cpp.

◆ factor()

void factor ( )

overridevirtual

Perform an LU decomposition, the LAPACK routine DGBTRF is used.

The factorization is saved in ludata.

Implements GeneralMatrix.

Definition at line 222 of file BandMatrix.cpp.

◆ solve() [1/2]

void solve	(	span< const double >	b,
		span< double >	x
	)

Solve the matrix problem Ax = b.

Parameters

b	INPUT RHS of the problem
x	OUTPUT solution to the problem

Definition at line 243 of file BandMatrix.cpp.

◆ solve() [2/2]

void solve	(	span< double >	b,
		size_t	nrhs = `1`,
		size_t	ldb = `0`
	)

overridevirtual

Solve the matrix problem Ax = b.

Parameters

b	INPUT RHS of the problem OUTPUT solution to the problem
nrhs	Number of right hand sides to solve
ldb	Leading dimension of `b`. Default is nColumns()

Implements GeneralMatrix.

Definition at line 251 of file BandMatrix.cpp.

◆ zero()

void zero ( )

overridevirtual

Zero the matrix elements.

Implements GeneralMatrix.

Definition at line 124 of file BandMatrix.cpp.

◆ rcond()

double rcond ( double a1norm )

overridevirtual

Returns an estimate of the inverse of the condition number for the matrix.

The matrix must have been previously factored using the LU algorithm

Parameters

a1norm Norm of the matrix

Returns: the inverse of the condition number

Implements GeneralMatrix.

Definition at line 291 of file BandMatrix.cpp.

◆ factorAlgorithm()

int factorAlgorithm ( ) const

overridevirtual

Returns the factor algorithm used.

This method will always return 0 (LU) for band matrices.

Implements GeneralMatrix.

Definition at line 314 of file BandMatrix.cpp.

◆ oneNorm()

double oneNorm ( ) const

overridevirtual

Returns the one norm of the matrix.

Implements GeneralMatrix.

Definition at line 319 of file BandMatrix.cpp.

◆ checkRows()

size_t checkRows ( double & valueSmall ) const

overridevirtual

Check to see if we have any zero rows in the Jacobian.

This utility routine checks to see if any rows are zero. The smallest row is returned along with the largest coefficient in that row

Parameters

valueSmall OUTPUT value of the largest coefficient in the smallest row

Returns: index of the row that is most nearly zero

Implements GeneralMatrix.

Definition at line 334 of file BandMatrix.cpp.

◆ checkColumns()

size_t checkColumns ( double & valueSmall ) const

overridevirtual

Check to see if we have any zero columns in the Jacobian.

This utility routine checks to see if any columns are zero. The smallest column is returned along with the largest coefficient in that column

Parameters

valueSmall OUTPUT value of the largest coefficient in the smallest column

Returns: index of the column that is most nearly zero

Implements GeneralMatrix.

Definition at line 356 of file BandMatrix.cpp.

◆ info()

int info ( ) const

inline

LAPACK "info" flag after last factor/solve operation.

Definition at line 197 of file BandMatrix.h.

Member Data Documentation

◆ data

vector<double> data

protected

Matrix data.

Definition at line 201 of file BandMatrix.h.

◆ ludata

vector<double> ludata

protected

Factorized data.

Definition at line 204 of file BandMatrix.h.

◆ m_lu_col_ptrs

vector<double*> m_lu_col_ptrs

protected

Pointers into ludata used by the SUNDIALS solver.

Definition at line 206 of file BandMatrix.h.

◆ m_n

size_t m_n = 0

protected

Number of rows and columns of the matrix.

Definition at line 209 of file BandMatrix.h.

◆ m_kl

size_t m_kl = 0

protected

Number of subdiagonals of the matrix.

Definition at line 212 of file BandMatrix.h.

◆ m_ku

size_t m_ku = 0

protected

Number of super diagonals of the matrix.

Definition at line 215 of file BandMatrix.h.

◆ m_zero

double m_zero = 0

protected

value of zero

Definition at line 218 of file BandMatrix.h.

◆ m_ipiv

unique_ptr<PivData> m_ipiv

protected

Pivot vector.

Definition at line 223 of file BandMatrix.h.

◆ iwork_

vector<int> iwork_

protected

Extra work array needed - size = n.

Definition at line 226 of file BandMatrix.h.

◆ work_

vector<double> work_

protected

Extra dp work array needed - size = 3n.

Definition at line 229 of file BandMatrix.h.

◆ m_info

int m_info = 0

protected

Definition at line 232 of file BandMatrix.h.

The documentation for this class was generated from the following files:

Detailed Description

Classes

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ BandMatrix() [1/3]

◆ ~BandMatrix()

◆ BandMatrix() [2/3]

◆ BandMatrix() [3/3]

Member Function Documentation

◆ operator=()

◆ resize()

◆ bfill()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ value() [1/2]

◆ value() [2/2]

◆ index()

◆ _value()

◆ nRows()

◆ nColumns()

◆ nSubDiagonals()

◆ nSuperDiagonals()

◆ ldim()

◆ mult()

◆ leftMult()

◆ factor()

◆ solve() [1/2]

◆ solve() [2/2]

◆ zero()

◆ rcond()

◆ factorAlgorithm()

◆ oneNorm()

◆ checkRows()

◆ checkColumns()

◆ info()

Member Data Documentation

◆ data

◆ ludata

◆ m_lu_col_ptrs

◆ m_n

◆ m_kl

◆ m_ku

◆ m_zero

◆ m_ipiv

◆ iwork_

◆ work_

◆ m_info