Diffpack Documentation

---

              Search  

---

SparseDS Class Reference

data structure for general sparse matrix storage. More...

#include <SparseDS.h>

Inheritance diagram for SparseDS::

List of all members.

Public Methods
	SparseDS ()
	SparseDS (int n, int max_nonzeroes)
	SparseDS (int nrows_, int ncolumns_, int max_nonzeroes)
	SparseDS (const VecSimple(VecSimple(int)) &col_idx)
	~SparseDS ()
bool	operator== (const SparseDS &X)
bool	consistent ()
bool	diagonalComputed () const
bool	computeDiagonal ()
bool	removeDiagonalInfo ()
bool	ok () const
bool	redim (int n, int max_nonzeroes)
bool	redim (int nrows, int ncolumns, int max_nonzeroes)
bool	redimIrow (int nrows_, int ncolumns_)
bool	redimIrow (int nrows_)
bool	fillJcol (DpList(int), DpListItemInst &jcol_list)
bool	fillJcol (VecSimple(int) &jcol_vector, const int no_nonzero)
void	fill (const VecSimple(VecSimple(int)) &col_idx)
int&	irow (int i)
int&	jcol (int i)
int&	diag (int i)
int	irow (int i) const
int	jcol (int i) const
int	diag (int i) const
int	idx (int i, int j) const
int	getNoRows () const
int	getNoColumns () const
int	maxNonZeroes () const
int	getNoNonzeroes () const
int&	getNoNonzeroes ()
const int*	getIrowPtr0 () const
int*	getIrowPtr0 ()
const int*	getJcolPtr0 () const
int*	getJcolPtr0 ()
void	endInit ()
void	createUnion (const SparseDS &A, const SparseDS &B)
bool	containedIn (const SparseDS &A) const
void	printPattern (Os os) const
void	print (Os os, const char *header=NULL, int nentries_per_line=3) const
void	scan (Is is)
	COPY_CONSTRUCTOR (SparseDS)
	ASSIGNMENT_OPERATOR (SparseDS)

---

Detailed Description

data structure for general sparse matrix storage.

NAME: SparseDS - data structure for general sparse matrix storage

DESCRIPTION:

The class defines a data structure and a public interface for representing a general sparse matrix. All the nonzero entries of the matrix are stored row by row in a vector. The matrix entries are not a part of this class. Two indexing functions are used for locating a matrix entry. It is these two functions, and related procedures, that are offered by class "SparseDS". The sparse matrix storage scheme is described in detail below.

Assume that all the `$`n`_`z`$` nonzeroes in an "nrows" by "ncolumns" matrix are stored in an array `$`A`_`s`$`, which will typically be a part of class "MatSparse". The information needed to subscript a sparse matrix is contained in class "SparseDS". To access the matrix entries two address arrays "irow" and "jcol" are needed. Here "irow(k)" gives the address in `$`A`_`s`$` of the first nonzero entry in row number `$`k`$` in the coefficient matrix, while "jcol(l)" gives the matrix column number of the entry `$`A`_`s(l)`$`.

$The following example illustrates this scheme for $n=5$: $\[\left( \begin{array}{ccccc} $ a_{1,1} & 0 & 0 & a_{1,4} & 0 \ $ 0 & a_{2,2}& a_{2,3}& 0 & a_{2,5} \ $ 0 & a_{3,2}& a_{3,3}& 0 & 0 \ $ a_{4,1} & 0 & 0 & a_{4,4} & a_{4,5} \ $ 0 & a_{5,2}& 0 & a_{5,4} & a_{5,5} \end{array}\right) \] $\begin{eqnarray*} $A_s & = &(a_{1,1},a_{1,4},a_{2,2},a_{2,3},a_{2,5},a_{3,2},a_{3,3},a_{4,1}, $a_{4,4},a_{4,5}, a_{5,2},a_{5,4},a_{5,5}) \ $\mbox{\tt irow} &=& (1,3,6,8,11,14) \ $\mbox{\tt jcol} &=& (1,4,2,3,5,2,3,1,4,5,2,4,5) $\end{eqnarray*} Notice that "irow" has dimension "nrows"+1 whereas `$`A`_`s`$` and "jcol" have dimension `$`n`_`z = `\mbox{`"irow"`}`(`\mbox{`"nrows"`}`+1)-1`$`.

---

Constructor & Destructor Documentation

SparseDS::SparseDS ( )

There are three constructors. With no arguments, the "redim" function must be called later to ensure that memory is allocated for the object. For the constructor with two arguments, the first represents the number of rows and columns and the second represents the number of unknowns. The constructor that takes three arguments, takes the number of rows in the matrix, the number of columns and the maximum number of nonzeroes as arguments. With these constructors or "redim" functions, only the internal data structures are allocated, and the user has to use the functions "irow", "jcol" and "getNoNonzeroes" to initialize the sparsity pattern (this is often done by the "makeSparsityPattern" functions). Another way of initializing the object is to use the constructor with no arguments and then the "redimIrow" function to allocate storage for the ""irow"" part of the data structure (the length of this is known when the number of rows in the matrix is known). Thereafter the programmer can make a list "DpList(int,DpListItemInst)" and add column (""jcol"") entries to this list in a flexible and storage minimizing way, along with filling ""irow"" values using the function "SparseDS irow". Finally, the list is submitted to the "SparseDS" object by calling the "fillJcol" function. In practice, the usage of "redimIrow" and "fillJcol" is the most flexible way of creating a "SparseDS" object. See also the documentation of the "redimIrow" function.

SparseDS::SparseDS ( int n, int max_nonzeroes ) [inline]

See documentation of one of the overloaded constructor.

SparseDS::SparseDS ( int nrows_, int ncolumns_, int max_nonzeroes ) [inline]

See documentation of one of the overloaded constructor.

SparseDS::SparseDS ( const VecSimple(VecSimple(int)) & col_idx )

See documentation of one of the overloaded constructor.

SparseDS::~SparseDS ( )

---

Member Function Documentation

SparseDS::ASSIGNMENT_OPERATOR ( SparseDS )

SparseDS::COPY_CONSTRUCTOR ( SparseDS )

bool SparseDS::computeDiagonal ( )

creates an array holding the indices of the elements of the diagonal in the matrix. This computation will increase the efficiency of many repeted calls to find the diagonal entries.

bool SparseDS::consistent ( )

checks the current object to see if the index information is valid.

bool SparseDS::containedIn ( const SparseDS & A ) const

returns "true" if all the elements of this object can be found in the supplied object and "false" if the objects represent matrices of different size or if one or more elements of this object can not be found in the supplied object.

void SparseDS::createUnion ( const SparseDS & A, const SparseDS & B )

initializes this objects with the union of the entries in the two supplied objects, that is any entry that can be found in one of or both supplied objects will be an entry in this object. The supplied objects must represent matrices of equal size, otherwise an error message will be given.

int SparseDS::diag ( int i ) const [inline]

See documentation of one of the overloaded functions.

int & SparseDS::diag ( int i ) [inline]

gives access to the specified entry in the diag_array.

bool SparseDS::diagonalComputed ( ) const [inline]

returns "true" if the index information of the diagonal elements has been computed.

void SparseDS::endInit ( )

to be called when the sparsity pattern is fully loaded.

void SparseDS::fill ( const VecSimple(VecSimple(int)) & col_idx )

fills the entire sparse structure based on the info in the argument to the function. The vector argument to the funcion has one entry for each row in the matrix. Each row entry is a vector of the column indices where there is an entry on the particular row.

bool SparseDS::fillJcol ( VecSimple(int) & jcol_vector, const int no_nonzero )

See documentation of one of the overloaded functions.

bool SparseDS::fillJcol ( DpList(int), DpListItemInst & jcol_list )

see the documentation of "redimIrow".

int * SparseDS::getIrowPtr0 ( ) [inline]

See documentation of one of the overloaded functions.

const int * SparseDS::getIrowPtr0 ( ) const [inline]

returns access to the underlying C array for the ""irow"" part of the "SparseDS" structure. The "0" in the name indicates that the returned pointer is the base of a C array where "[0]" is the first element. This is the function to be used when, for example, communicating with Fortran programs.

int * SparseDS::getJcolPtr0 ( ) [inline]

See documentation of one of the overloaded functions.

const int * SparseDS::getJcolPtr0 ( ) const [inline]

as "getIrowPtr0", but access to the ""jcol"" array is returned.

int SparseDS::getNoColumns ( ) const [inline]

return the number of columns.

int & SparseDS::getNoNonzeroes ( ) [inline]

See documentation of one of the overloaded functions.

int SparseDS::getNoNonzeroes ( ) const [inline]

returns the number of nonzeros actually stored by now. It can also be used to set this value.

int SparseDS::getNoRows ( ) const [inline]

return the number of rows.

int SparseDS::idx ( int i, int j ) const

returns the index in the jcol-array that corresponds to supplied indices. If the j-index is not found, "0" is returned.

int SparseDS::irow ( int i ) const [inline]

See documentation of one of the overloaded functions.

int & SparseDS::irow ( int i ) [inline]

gives access to the specified entry in the irow_array.

int SparseDS::jcol ( int i ) const [inline]

See documentation of one of the overloaded functions.

int & SparseDS::jcol ( int i ) [inline]

gives access to the specified entry in the jcol_array.

int SparseDS::maxNonZeroes ( ) const [inline]

returns the maximum number of nonzero elements in the current "SparseDS" object.

bool SparseDS::ok ( ) const

bool SparseDS::operator== ( const SparseDS & X )

void SparseDS::print ( Os os, const char * header = NULL, int nentries_per_line = 3 ) const

prints the sparsity pattern data on the specified output stream.

void SparseDS::printPattern ( Os os ) const

prints a graphical representation of the sparsity pattern on the specified output stream. (Works only for reasonable small matrices).

bool SparseDS::redim ( int nrows, int ncolumns, int max_nonzeroes )

See documentation of one of the overloaded functions.

bool SparseDS::redim ( int n, int max_nonzeroes ) [inline]

See documentation of one of the overloaded functions.

bool SparseDS::redimIrow ( int nrows_ ) [inline]

See documentation of one of the overloaded functions.

bool SparseDS::redimIrow ( int nrows_, int ncolumns_ )

allocates storage for the ""irow"" part of the data structure. This can be done before the sparsity pattern is known, and during the computation of the sparsity pattern, one can then easily fill in ""irow"" values using the "irow" function. Simultaneously, the programmer can use a local list "DpList(int,DpListItemInst)" to compute the column (""jcol"") numbers. Since the number of nonzeroes is not known on beforehand, a local list is a flexible way of storing the column number information. After the list is computed, it is submitted to the "SparseDS" object by calling "fillJcol" and the "SparseDS" is completely initialized. Using "redimIrow" and "fillJcol" the "SparseDS" object will allocated the exact amount of memory needed to store the sparsity pattern. If the "redim(int)" or "redim(int,int)" function is used, the internal arrays in "SparseDS" must be large enough to hold the expected sparsity pattern.

bool SparseDS::removeDiagonalInfo ( ) [inline]

remove the information computed about the diagonal. After this call, the "diagonalComputed" function will return false until a new call to "computeDiagonal" has been made.

void SparseDS::scan ( Is is )

scans the sparsity pattern data from the specified input stream.

---

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

• SparseDS.h

---