Tpetra::CisMatrix

Tpetra::CisMatrix< OrdinalType, ScalarType > Class Template Reference

Tpetra::CisMatrix: A class for constructing and using sparse compressed index matrices. More...

#include <Tpetra_CisMatrix.hpp>

Inheritance diagram for Tpetra::CisMatrix< OrdinalType, ScalarType >:

[legend]Collaboration diagram for Tpetra::CisMatrix< OrdinalType, ScalarType >:


Public Member Functions

	CisMatrix (VectorSpace< OrdinalType, ScalarType > const &primaryDist, bool rowOriented=true)
	Constructor specifying the primary distribution only.
	CisMatrix (VectorSpace< OrdinalType, ScalarType > const &primaryDist, VectorSpace< OrdinalType, ScalarType > const &secondaryDist, bool rowOriented=true)
	Constructor specifying both primary and secondary distributions.
	CisMatrix (CisMatrix< OrdinalType, ScalarType > const &Source)
	copy constructor.

void	setAllToScalar (ScalarType scalarThis)
	Set all matrix entries equal to scalarThis.
void	scale (ScalarType scalarThis)
	Scale the current values of a matrix, this = scalarThis*this.
void	submitEntry (CombineMode CM, OrdinalType const myRowOrColumn, ScalarType const value, OrdinalType const index)
	Submit a single entry, using global IDs.
void	submitEntries (CombineMode CM, OrdinalType const myRowOrColumn, OrdinalType const numEntries, ScalarType const values, OrdinalType const indices)
	Submit multiple entries, using global IDs.
void	fillComplete ()
	Signals that data entry is complete. Matrix data is converted into a more optimized form.
void	fillComplete (VectorSpace< OrdinalType, ScalarType > const &domainSpace, VectorSpace< OrdinalType, ScalarType > const &rangeSpace)
	Signals that data entry is complete. Matrix data is converted into a more optimized form.

ScalarType	normOne () const
	Returns the global one norm of the matrix.
ScalarType	normInf () const
	Returns the global infinity norm of the matrix.

OrdinalType	getNumGlobalNonzeros () const
	Returns the number of nonzero entries in the global matrix.
OrdinalType	getNumMyNonzeros () const
	Returns the number of nonzero entries in the calling image's portion of the matrix.
OrdinalType	getNumGlobalRows () const
	Returns the number of global matrix rows.
OrdinalType	getNumGlobalCols () const
	Returns the number of global matrix columns.
OrdinalType	getNumMyRows () const
	Returns the number of matrix rows owned by the calling image.
OrdinalType	getNumMyCols () const
	Returns the number of matrix columns owned by the calling image.
OrdinalType	getNumGlobalDiagonals () const
	Returns the number of global nonzero diagonal entries, based on global row/column index comparisons.
OrdinalType	getNumMyDiagonals () const
	Returns the number of local nonzero diagonal entries, based on global row/column index comparisons.
OrdinalType	getNumEntries (OrdinalType index) const
	Returns the current number of nonzero entries in specified global index on this image.
OrdinalType	getGlobalMaxNumEntries () const
	Returns the maximum number of nonzero entries across all rows/columns on all images.
OrdinalType	getMyMaxNumEntries () const
	Returns the maximum number of nonzero entries across all rows/columns on this image.
OrdinalType	getIndexBase () const
	Returns the index base for global indices for this matrix.
bool	isRowOriented () const
	Returns true if this matrix is row-oriented, and false if this matrix is column-oriented.
bool	isFillCompleted () const
	Returns true if the state of this matrix is post-fillComplete, and false if it is pre-fillComplete.
VectorSpace< OrdinalType, ScalarType > const &	getPrimaryDist () const
	Returns the VectorSpace that describes the primary distribution in this matrix.
VectorSpace< OrdinalType, ScalarType > const &	getSecondaryDist () const
	Returns the VectorSpace that describes the secondary distribution in this matrix.
VectorSpace< OrdinalType, ScalarType > const &	getRowDist () const
	Returns the VectorSpace that describes the row distribution in this matrix.
VectorSpace< OrdinalType, ScalarType > const &	getColumnDist () const
	Returns the VectorSpace that describes the column distribution in this matrix.
Platform< OrdinalType, ScalarType > const &	platform () const
	Returns the Platform object used by this matrix.

void	print (ostream &os) const

CisMatrix< OrdinalType, ScalarType > &	operator= (CisMatrix< OrdinalType, ScalarType > const &Source)
	Assignment operator.
Overridden from Tpetra::Operator
VectorSpace< OrdinalType, ScalarType > const &	getDomainDist () const

VectorSpace< OrdinalType, ScalarType > const &	getRangeDist () const

void	apply (Vector< OrdinalType, ScalarType > const &x, Vector< OrdinalType, ScalarType > &y, bool transpose=false) const

Detailed Description

template<typename OrdinalType, typename ScalarType>
class Tpetra::CisMatrix< OrdinalType, ScalarType >

Tpetra::CisMatrix: A class for constructing and using sparse compressed index matrices.

CisMatrix enables the piecewise construction and use of sparse matrices where matrix entries are intended for either row or column access.

At this time, the primary function provided by CisMatrix is matrix times vector and multiplication. It is also possible to extract a Kokkos::HBMatrix so that a Tpetra::CisMatrix can be used in Kokkos kernels.

Constructing CisMatrix objects

Constructing CisMatrix objects is a multi-step process. The basic steps are as follows:

Create a CisMatrix instance, using one of the constructors.
Enter values using the submitEntries methods.
Complete construction by calling fillComplete.

Primary and Secondary Distributions CisMatrix stores data using Compressed Index Space Storage. This is a generalization of Compressed Row Storage, but allows the matrix to be either row-oriented or column oriented. Accordingly, CisMatrix refers to data using a generalized vocabulary. The two main terms are the primary distribution and the secondary distribution:

In a row-oriented matrix, the primary distribution refers to rows, and the secondary distribution refers to columns. In a column-oriented matrix, the primary distribution refers to columns, and the secondary distribution refers to rows.

These distributions are specified by Tpetra::VectorSpace objects. If both the primary and secondary distributions are specified at construction, information about the secondary distribution is available from then on. But if only the primary distribution is specified at construction, then CisMatrix will analyze the structure of the matrix and generate a VectorSpace that matches the distribution found in the matrix. Note that this is done when fillComplete is called, and so information about the secondary distribution is not available prior to that.

FillComplete A Tpetra::CisMatrix exists in one of two states. Prior to calling fillComplete, data is stored in a format optimized for easy and efficient insertions/deletions/modifications. It is not a very efficient form for doing matvec operations though. After calling fillComplete, the data is transformed into a format optimized for matvec operations. It is not very efficient at modifying data though. So after fillComplete has been called, the matrix should be viewed as const, and cannot be modified. Trying to do so will result in an exception being thrown.

Counting Floating Point Operations

CisMatrix inherits from Teuchos::CompObject, and keeps track of the number of floating point operations associated with the this object. In conjunction with a timing object (such as Teuchos::Time), accurate parallel performance information can be obtained. Further information can be found in the Teuchos documentation.

CisMatrix error codes (positive for non-fatal, negative for fatal):

+1 That global ID is not owned by this image.
+2 Unsupported combine mode specified.
+3 Requested distribution is not currently defined.
+4 Cannot call that method until after fillComplete.
+5 Cannot call that method after fillComplete.
+6 Distribution mismatch.
-99 Internal CisMatrix error. Contact developer.