Epetra_BasicRowMatrix Class Reference

Epetra_BasicRowMatrix: A class for simplifying the development of Epetra_RowMatrix adapters. More...

#include <Epetra_BasicRowMatrix.h>

Inheritance diagram for Epetra_BasicRowMatrix:

[legend]Collaboration diagram for Epetra_BasicRowMatrix:[legend]List of all members.

Public Member Functions
Constructor/Destructor
	Epetra_BasicRowMatrix (const Epetra_Comm &Comm)
	Epetra_BasicRowMatrix constuctor.
virtual	~Epetra_BasicRowMatrix ()
	Epetra_BasicRowMatrix Destructor.
Setup functions
void	SetMaps (const Epetra_Map &RowMap, const Epetra_Map &ColMap)
	Set maps (Version 1); call this function or the next, but not both.
void	SetMaps (const Epetra_Map &RowMap, const Epetra_Map &ColMap, const Epetra_Map &DomainMap, const Epetra_Map &RangeMap)
	Set maps (Version 2); call this function or the previous, but not both.
User-required implementation methods
virtual int	ExtractMyRowCopy (int MyRow, int Length, int &NumEntries, double *Values, int *Indices) const =0
	Returns a copy of the specified local row in user-provided arrays.
virtual int	ExtractMyEntryView (int CurEntry, double *&Value, int &RowIndex, int &ColIndex)=0
	Returns a reference to the ith entry in the matrix, along with its row and column index.
virtual int	ExtractMyEntryView (int CurEntry, double const *&Value, int &RowIndex, int &ColIndex) const =0
	Returns a const reference to the ith entry in the matrix, along with its row and column index.
virtual int	NumMyRowEntries (int MyRow, int &NumEntries) const =0
	Return the current number of values stored for the specified local row.
Computational methods
virtual int	Multiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_BasicRowMatrix multiplied by a Epetra_MultiVector X in Y.
virtual int	Solve (bool Upper, bool Trans, bool UnitDiagonal, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_BasicRowMatrix solve with a Epetra_MultiVector X in Y (not implemented).
virtual int	ExtractDiagonalCopy (Epetra_Vector &Diagonal) const
	Returns a copy of the main diagonal in a user-provided vector.
virtual int	InvRowSums (Epetra_Vector &x) const
	Computes the sum of absolute values of the rows of the Epetra_BasicRowMatrix, results returned in x.
virtual int	LeftScale (const Epetra_Vector &x)
	Scales the Epetra_BasicRowMatrix on the left with a Epetra_Vector x.
virtual int	InvColSums (Epetra_Vector &x) const
	Computes the sum of absolute values of the columns of the Epetra_BasicRowMatrix, results returned in x.
virtual int	RightScale (const Epetra_Vector &x)
	Scales the Epetra_BasicRowMatrix on the right with a Epetra_Vector x.
Matrix Properties Query Methods
virtual bool	Filled () const
	If FillComplete() has been called, this query returns true, otherwise it returns false, presently always returns true.
bool	LowerTriangular () const
	If matrix is lower triangular, this query returns true, otherwise it returns false.
virtual bool	UpperTriangular () const
	If matrix is upper triangular, this query returns true, otherwise it returns false.
Atribute access functions
virtual double	NormInf () const
	Returns the infinity norm of the global matrix.
virtual double	NormOne () const
	Returns the one norm of the global matrix.
virtual int	NumGlobalNonzeros () const
	Returns the number of nonzero entries in the global matrix.
virtual int	NumGlobalRows () const
	Returns the number of global matrix rows.
virtual int	NumGlobalCols () const
	Returns the number of global matrix columns.
virtual int	NumGlobalDiagonals () const
	Returns the number of global nonzero diagonal entries.
virtual int	NumMyNonzeros () const
	Returns the number of nonzero entries in the calling processor's portion of the matrix.
virtual int	NumMyRows () const
	Returns the number of matrix rows owned by the calling processor.
virtual int	NumMyCols () const
	Returns the number of matrix columns owned by the calling processor.
virtual int	NumMyDiagonals () const
	Returns the number of local nonzero diagonal entries.
virtual int	MaxNumEntries () const
	Returns the maximum number of nonzero entries across all rows on this processor.
virtual const Epetra_Map &	OperatorDomainMap () const
	Returns the Epetra_Map object associated with the domain of this operator.
virtual const Epetra_Map &	OperatorRangeMap () const
	Returns the Epetra_Map object associated with the range of this operator (same as domain).
virtual const Epetra_BlockMap &	Map () const
	Implement the Epetra_SrcDistObjec::Map() function.
virtual const Epetra_Map &	RowMatrixRowMap () const
	Returns the Row Map object needed for implementing Epetra_RowMatrix.
virtual const Epetra_Map &	RowMatrixColMap () const
	Returns the Column Map object needed for implementing Epetra_RowMatrix.
virtual const Epetra_Import *	RowMatrixImporter () const
	Returns the Epetra_Import object that contains the import operations for distributed operations.
virtual const Epetra_Comm &	Comm () const
	Returns a pointer to the Epetra_Comm communicator associated with this matrix.
I/O Methods
virtual void	Print (ostream &os) const
	Print method.
Additional methods required to support the Epetra_RowMatrix interface
virtual int	SetUseTranspose (bool UseTranspose)
	If set true, transpose of this operator will be applied.
virtual const char *	Label () const
	Returns a character string describing the operator.
virtual int	Apply (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_RowMatrix applied to a Epetra_MultiVector X in Y.
virtual int	ApplyInverse (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_RowMatrix inverse applied to an Epetra_MultiVector X in Y.
bool	HasNormInf () const
	Returns true because this class can compute an Inf-norm.
virtual bool	UseTranspose () const
	Returns the current UseTranspose setting.
Additional accessor methods
virtual const Epetra_Import *	Importer () const
	Returns the Epetra_Import object that contains the import operations for distributed operations, returns zero if none.
virtual const Epetra_Export *	Exporter () const
	Returns the Epetra_Export object that contains the export operations for distributed operations, returns zero if none.
Protected Member Functions
void	Setup ()
void	UpdateImportVector (int NumVectors) const
void	UpdateExportVector (int NumVectors) const
void	SetImportExport ()
Post-construction modifications
virtual void	ComputeStructureConstants () const
	Update the constants associated with the structure of the matrix: Call only if structure changes from the initial RowMatrix.
virtual void	ComputeNumericConstants () const
	Update the constants associated with the values of the matrix: Call only if values changes from the initial RowMatrix.
Protected Attributes
Epetra_Comm *	Comm_
Epetra_Map	OperatorDomainMap_
Epetra_Map	OperatorRangeMap_
Epetra_Map	RowMatrixRowMap_
Epetra_Map	RowMatrixColMap_
int	NumMyNonzeros_
int	NumGlobalNonzeros_
int	MaxNumEntries_
double	NormInf_
double	NormOne_
int	NumMyRows_
int	NumMyCols_
bool	UseTranspose_
bool	HasNormInf_
bool	LowerTriangular_
bool	UpperTriangular_
bool	HaveStructureConstants_
bool	HaveNumericConstants_
bool	HaveMaps_
Epetra_MultiVector *	ImportVector_
Epetra_MultiVector *	ExportVector_
Epetra_Import *	Importer_
Epetra_Export *	Exporter_

---

Detailed Description

Epetra_BasicRowMatrix: A class for simplifying the development of Epetra_RowMatrix adapters.

The Epetra_BasicRowMatrix is an adapter class for Epetra_RowMatrix that implements most of the Epetra_RowMatrix methods using reasonable default implementations. The Epetra_RowMatrix class has 39 pure virtual methods, requiring the adapter class to implement all of them. Epetra_BasicRowMatrix has only 4 pure virtual methods that must be implemented:

1. ExtractMyRowCopy: Provide a row of values and indices for a specified local row.
2. ExtractMyEntriyView (const and non-const versions): Provide the memory address of the ith nonzero term stored on the calling processor, along with its corresponding local row and column index, where i goes from 0 to the NumMyNonzeros()-1. The order in which the nonzeros are traversed is not specified and is up to the adapter implementation.
3. NumMyRowEntries: Provide the number of entries for a specified local row.

In addition, most adapters will probably re-implement the Multiply() method and perhaps the Solve() method, although one or the other may be implemented to return -1, signaling that there is no valid implementation. By default, the Multiply() method is implemented using ExtractMyRowCopy, which can usual be improved upon. By default Solve() and ApplyInverse() are implemented to return -1 (not implemented).

All other implemented methods in Epetra_BasicRowMatrix should not exhibit a signficant performance degradation, either because they are relatively small and fast, or because they are not a significant portion of the runtime for most codes. All methods are virtual, so they can be re-implemented by the adapter.

In addition to implementing the above methods, an adapter must inherit the Epetra_BasicRowMatrix interface and call the Epetra_BasicRowMatrix constructor as part of the adapter constructor. There are two constructors. The first requires the user to pass in the RowMap and ColMap, both of which are Epetra_Map objects. On each processor the RowMap (ColMap) must contain the global IDs (GIDs) of the rows (columns) that the processor cares about. The first constructor requires only these two maps, assuming that the RowMap will also serve as the DomainMap and RangeMap. In this case, the RowMap must be 1-to-1, meaning that if a global ID appears on one processor, it appears only once on that processor and does not appear on any other processor. For many sparse matrix data structures, it is the case that a given row is completely owned by one processor and that the global matrix is square. The first constructor is for this situation.

The second constructor allows the caller to specify all four maps. In this case the DomainMap, the layout of multivectors/vectors that are in the domain of the matrix (the x vector if computing y = A*x), must be 1-to-1. Also, the RangeMap, the layout of y must be 1-to-1. The RowMap and ColMap do not need to be 1-to-1, but the GIDs must be found in the RangeMap and DomainMap, respectively.

Note that Epetra_Operator is a base class for Epetra_RowMatrix, so any adapter for Epetra_BasicRowMatrix (or Epetra_RowMatrix) is also an adapter for Epetra_Operator.

An example of how to provide an adapter for Epetra_BasicRowMatrix can be found by looking at Epetra_JadMatrix.

---

Member Function Documentation

virtual int Epetra_BasicRowMatrix::Apply (  const Epetra_MultiVector &  X, Epetra_MultiVector &  Y )  const [inline, virtual]

Returns the result of a Epetra_RowMatrix applied to a Epetra_MultiVector X in Y. Parameters: X  (In) - A Epetra_MultiVector of dimension NumVectors to multiply with matrix. Y  (Out) - A Epetra_MultiVector of dimension NumVectors containing result. Returns: Integer error code, set to 0 if successful. Implements Epetra_Operator.

virtual int Epetra_BasicRowMatrix::ApplyInverse (  const Epetra_MultiVector &  X, Epetra_MultiVector &  Y )  const [inline, virtual]

Returns the result of a Epetra_RowMatrix inverse applied to an Epetra_MultiVector X in Y. Parameters: X  (In) - A Epetra_MultiVector of dimension NumVectors to solve for. Y  (Out) - A Epetra_MultiVector of dimension NumVectors containing result. Returns: Integer error code = -1. Warning: This method is NOT supported. Implements Epetra_Operator.

virtual const Epetra_Export* Epetra_BasicRowMatrix::Exporter (   )  const [inline, virtual]

Returns the Epetra_Export object that contains the export operations for distributed operations, returns zero if none. If RowMatrixRowMap!=OperatorRangeMap, then this method returns a pointer to an Epetra_Export object that exports objects from an RowMatrixRowMap layout to a OperatorRangeMap layout. This operation is needed for sparse matrix-vector multiplication, y = Ax, to scatter-add y elements generated during local multiplication operations. If RowMatrixRowMap==OperatorRangeMap, then the pointer will be returned as 0. For a typical Epetra_RowMatrix object, this pointer will be zero since it is often the case that RowMatrixRowMap==OperatorRangeMap. Returns: Raw pointer to exporter. This exporter will be valid as long as the Epetra_RowMatrix object is valid.

virtual int Epetra_BasicRowMatrix::ExtractDiagonalCopy (  Epetra_Vector &  Diagonal  )  const [virtual]

Returns a copy of the main diagonal in a user-provided vector. Parameters: Diagonal  (Out) - Extracted main diagonal. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix.

virtual int Epetra_BasicRowMatrix::ExtractMyEntryView (  int  CurEntry, double const *&  Value, int &  RowIndex, int &  ColIndex )  const [pure virtual]

Returns a const reference to the ith entry in the matrix, along with its row and column index. Parameters: CurEntry  (In) - Local entry to extract. Value  (Out) - Extracted reference to current values. RowIndex  (Out) - Row index for current entry. ColIndex  (Out) - Column index for current entry. Returns: Integer error code, set to 0 if successful, set to -1 if CurEntry not valid. Implemented in Epetra_JadMatrix.

virtual int Epetra_BasicRowMatrix::ExtractMyEntryView (  int  CurEntry, double *&  Value, int &  RowIndex, int &  ColIndex )  [pure virtual]

Returns a reference to the ith entry in the matrix, along with its row and column index. Parameters: CurEntry  (In) - Local entry to extract. Value  (Out) - Extracted reference to current values. RowIndex  (Out) - Row index for current entry. ColIndex  (Out) - Column index for current entry. Returns: Integer error code, set to 0 if successful, set to -1 if CurEntry not valid. Implemented in Epetra_JadMatrix.

virtual int Epetra_BasicRowMatrix::ExtractMyRowCopy (  int  MyRow, int  Length, int &  NumEntries, double *  Values, int *  Indices )  const [pure virtual]

Returns a copy of the specified local row in user-provided arrays. Parameters: MyRow  (In) - Local row to extract. Length  (In) - Length of Values and Indices. NumEntries  (Out) - Number of nonzero entries extracted. Values  (Out) - Extracted values for this row. Indices  (Out) - Extracted global column indices for the corresponding values. Returns: Integer error code, set to 0 if successful, set to -1 if MyRow not valid, -2 if Length is too short (NumEntries will have required length). Implements Epetra_RowMatrix. Implemented in Epetra_JadMatrix.

virtual const Epetra_Import* Epetra_BasicRowMatrix::Importer (   )  const [inline, virtual]

Returns the Epetra_Import object that contains the import operations for distributed operations, returns zero if none. If RowMatrixColMap!=OperatorDomainMap, then this method returns a pointer to an Epetra_Import object that imports objects from an OperatorDomainMap layout to a RowMatrixColMap layout. This operation is needed for sparse matrix-vector multiplication, y = Ax, to gather x elements for local multiplication operations. If RowMatrixColMap==OperatorDomainMap, then the pointer will be returned as 0. Returns: Raw pointer to importer. This importer will be valid as long as the Epetra_RowMatrix object is valid.

virtual int Epetra_BasicRowMatrix::InvColSums (  Epetra_Vector &  x  )  const [virtual]

Computes the sum of absolute values of the columns of the Epetra_BasicRowMatrix, results returned in x. The vector x will return such that x[j] will contain the inverse of sum of the absolute values of the this matrix will be sca such that A(i,j) = x(j)*A(i,j) where i denotes the global row number of A and j denotes the global column number of A. Using the resulting vector from this function as input to RighttScale() will make the one norm of the resulting matrix exactly 1. Parameters: x  (Out) - An Epetra_Vector containing the column sums of the this matrix. Warning: It is assumed that the distribution of x is the same as the rows of this. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix.

virtual int Epetra_BasicRowMatrix::InvRowSums (  Epetra_Vector &  x  )  const [virtual]

Computes the sum of absolute values of the rows of the Epetra_BasicRowMatrix, results returned in x. The vector x will return such that x[i] will contain the inverse of sum of the absolute values of the this matrix will be scaled such that A(i,j) = x(i)*A(i,j) where i denotes the global row number of A and j denotes the global column number of A. Using the resulting vector from this function as input to LeftScale() will make the infinity norm of the resulting matrix exactly 1. Parameters: x  (Out) - An Epetra_Vector containing the row sums of the this matrix. Warning: It is assumed that the distribution of x is the same as the rows of this. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix.

virtual int Epetra_BasicRowMatrix::LeftScale (  const Epetra_Vector &  x  )  [virtual]

Scales the Epetra_BasicRowMatrix on the left with a Epetra_Vector x. The this matrix will be scaled such that A(i,j) = x(i)*A(i,j) where i denotes the row number of A and j denotes the column number of A. Parameters: x  (In) - An Epetra_Vector to solve for. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix.

virtual int Epetra_BasicRowMatrix::Multiply (  bool  TransA, const Epetra_MultiVector &  X, Epetra_MultiVector &  Y )  const [virtual]

Returns the result of a Epetra_BasicRowMatrix multiplied by a Epetra_MultiVector X in Y. Parameters: TransA  (In) - If true, multiply by the transpose of matrix, otherwise just use matrix. X  (Out) - An Epetra_MultiVector of dimension NumVectors to multiply with matrix. Y  (Out) - An Epetra_MultiVector of dimension NumVectorscontaining result. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix. Reimplemented in Epetra_JadMatrix.

virtual int Epetra_BasicRowMatrix::NumMyRowEntries (  int  MyRow, int &  NumEntries )  const [pure virtual]

Return the current number of values stored for the specified local row. Similar to NumMyEntries() except NumEntries is returned as an argument and error checking is done on the input value MyRow. Parameters: MyRow  (In) - Local row. NumEntries  (Out) - Number of nonzero values. Returns: Integer error code, set to 0 if successful, set to -1 if MyRow not valid. Implements Epetra_RowMatrix. Implemented in Epetra_JadMatrix.

virtual int Epetra_BasicRowMatrix::RightScale (  const Epetra_Vector &  x  )  [virtual]

Scales the Epetra_BasicRowMatrix on the right with a Epetra_Vector x. The this matrix will be scaled such that A(i,j) = x(j)*A(i,j) where i denotes the global row number of A and j denotes the global column number of A. Parameters: x  (In) - The Epetra_Vector used for scaling this. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix.

virtual int Epetra_BasicRowMatrix::SetUseTranspose (  bool  UseTranspose  )  [inline, virtual]

If set true, transpose of this operator will be applied. This flag allows the transpose of the given operator to be used implicitly. Setting this flag affects only the Apply() and ApplyInverse() methods. If the implementation of this interface does not support transpose use, this method should return a value of -1. Parameters: UseTranspose  (In) - If true, multiply by the transpose of operator, otherwise just use operator. Returns: Always returns 0. Implements Epetra_Operator.

virtual int Epetra_BasicRowMatrix::Solve (  bool  Upper, bool  Trans, bool  UnitDiagonal, const Epetra_MultiVector &  X, Epetra_MultiVector &  Y )  const [inline, virtual]

Returns the result of a Epetra_BasicRowMatrix solve with a Epetra_MultiVector X in Y (not implemented). Parameters: Upper  (In) - If true, solve Ux = y, otherwise solve Lx = y. Trans  (In) - If true, solve transpose problem. UnitDiagonal  (In) - If true, assume diagonal is unit (whether it's stored or not). X  (In) - An Epetra_MultiVector of dimension NumVectors to solve for. Y  (Out) - An Epetra_MultiVector of dimension NumVectors containing result. Returns: Integer error code, set to 0 if successful. Implements Epetra_RowMatrix. Reimplemented in Epetra_JadMatrix.

---

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

• Epetra_BasicRowMatrix.h

---