Epetra_CrsMatrix Class Reference

Epetra_CrsMatrix: A class for constructing and using real-valued double-precision sparse compressed row matrices. More...

#include <Epetra_CrsMatrix.h>

Inheritance diagram for Epetra_CrsMatrix:

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

Public Member Functions
Constructors/Destructor.
	Epetra_CrsMatrix (Epetra_DataAccess CV, const Epetra_Map &RowMap, const int *NumEntriesPerRow, bool StaticProfile=false)
	Epetra_CrsMatrix constructor with variable number of indices per row.
	Epetra_CrsMatrix (Epetra_DataAccess CV, const Epetra_Map &RowMap, int NumEntriesPerRow, bool StaticProfile=false)
	Epetra_CrsMatrix constructor with fixed number of indices per row.
	Epetra_CrsMatrix (Epetra_DataAccess CV, const Epetra_Map &RowMap, const Epetra_Map &ColMap, const int *NumEntriesPerRow, bool StaticProfile=false)
	Epetra_CrsMatrix constructor with variable number of indices per row.
	Epetra_CrsMatrix (Epetra_DataAccess CV, const Epetra_Map &RowMap, const Epetra_Map &ColMap, int NumEntriesPerRow, bool StaticProfile=false)
	Epetra_CrsMatrix constuctor with fixed number of indices per row.
	Epetra_CrsMatrix (Epetra_DataAccess CV, const Epetra_CrsGraph &Graph)
	Construct a matrix using an existing Epetra_CrsGraph object.
	Epetra_CrsMatrix (const Epetra_CrsMatrix &Matrix)
	Copy constructor.
virtual	~Epetra_CrsMatrix ()
	Epetra_CrsMatrix Destructor.
Insertion/Replace/SumInto methods.
Epetra_CrsMatrix &	operator= (const Epetra_CrsMatrix &src)
	Assignment operator.
int	PutScalar (double ScalarConstant)
	Initialize all values in the matrix with constant value.
int	Scale (double ScalarConstant)
	Multiply all values in the matrix by a constant value (in place: A <- ScalarConstant * A).
int	InsertGlobalValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
	Insert a list of elements in a given global row of the matrix.
int	ReplaceGlobalValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
	Replace specified existing values with this list of entries for a given global row of the matrix.
int	SumIntoGlobalValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
	Add this list of entries to existing values for a given global row of the matrix.
int	InsertMyValues (int MyRow, int NumEntries, double *Values, int *Indices)
	Insert a list of elements in a given local row of the matrix.
int	ReplaceMyValues (int MyRow, int NumEntries, double *Values, int *Indices)
	Replace current values with this list of entries for a given local row of the matrix.
int	SumIntoMyValues (int MyRow, int NumEntries, double *Values, int *Indices)
	Add this list of entries to existing values for a given local row of the matrix.
int	ReplaceDiagonalValues (const Epetra_Vector &Diagonal)
	Replaces diagonal values of the matrix with those in the user-provided vector.
Transformation methods
int	FillComplete ()
	Signal that data entry is complete. Perform transformations to local index space.
int	FillComplete (const Epetra_Map &DomainMap, const Epetra_Map &RangeMap)
	Signal that data entry is complete. Perform transformations to local index space.
int	OptimizeStorage ()
	Make consecutive row index sections contiguous, minimize internal storage used for constructing graph.
int	MakeDataContiguous ()
	Eliminates memory that is used for construction. Make consecutive row index sections contiguous.
Extraction methods.
int	ExtractGlobalRowCopy (int GlobalRow, int Length, int &NumEntries, double *Values, int *Indices) const
	Returns a copy of the specified global row in user-provided arrays.
int	ExtractMyRowCopy (int MyRow, int Length, int &NumEntries, double *Values, int *Indices) const
	Returns a copy of the specified local row in user-provided arrays.
int	ExtractGlobalRowCopy (int GlobalRow, int Length, int &NumEntries, double *Values) const
	Returns a copy of the specified global row values in user-provided array.
int	ExtractMyRowCopy (int MyRow, int Length, int &NumEntries, double *Values) const
	Returns a copy of the specified local row values in user-provided array.
int	ExtractDiagonalCopy (Epetra_Vector &Diagonal) const
	Returns a copy of the main diagonal in a user-provided vector.
int	ExtractGlobalRowView (int GlobalRow, int &NumEntries, double *&Values, int *&Indices) const
	Returns a view of the specified global row values via pointers to internal data.
int	ExtractMyRowView (int MyRow, int &NumEntries, double *&Values, int *&Indices) const
	Returns a view of the specified local row values via pointers to internal data.
int	ExtractGlobalRowView (int GlobalRow, int &NumEntries, double *&Values) const
	Returns a view of the specified global row values via pointers to internal data.
int	ExtractMyRowView (int MyRow, int &NumEntries, double *&Values) const
	Returns a view of the specified local row values via pointers to internal data.
Computational methods.
int	Multiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y) const
	Returns the result of a Epetra_CrsMatrix multiplied by a Epetra_Vector x in y.
int	Multiply1 (bool TransA, const Epetra_Vector &x, Epetra_Vector &y) const
int	Multiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_CrsMatrix multiplied by a Epetra_MultiVector X in Y.
int	Multiply1 (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
int	Solve (bool Upper, bool Trans, bool UnitDiagonal, const Epetra_Vector &x, Epetra_Vector &y) const
	Returns the result of a local solve using the Epetra_CrsMatrix on a Epetra_Vector x in y.
int	Solve (bool Upper, bool Trans, bool UnitDiagonal, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a local solve using the Epetra_CrsMatrix a Epetra_MultiVector X in Y.
int	InvRowSums (Epetra_Vector &x) const
	Computes the inverse of the sum of absolute values of the rows of the Epetra_CrsMatrix, results returned in x.
int	InvRowMaxs (Epetra_Vector &x) const
	Computes the max of absolute values of the rows of the Epetra_CrsMatrix, results returned in x.
int	LeftScale (const Epetra_Vector &x)
	Scales the Epetra_CrsMatrix on the left with a Epetra_Vector x.
int	InvColSums (Epetra_Vector &x) const
	Computes the inverse of the sum of absolute values of the columns of the Epetra_CrsMatrix, results returned in x.
int	InvColMaxs (Epetra_Vector &x) const
	Computes the max of absolute values of the columns of the Epetra_CrsMatrix, results returned in x.
int	RightScale (const Epetra_Vector &x)
	Scales the Epetra_CrsMatrix on the right with a Epetra_Vector x.
Matrix Properties Query Methods.
bool	Filled () const
	If FillComplete() has been called, this query returns true, otherwise it returns false.
bool	StorageOptimized () const
	If OptimizeStorage() has been called, this query returns true, otherwise it returns false.
bool	IndicesAreGlobal () const
	If matrix indices has not been transformed to local, this query returns true, otherwise it returns false.
bool	IndicesAreLocal () const
	If matrix indices has been transformed to local, this query returns true, otherwise it returns false.
bool	IndicesAreContiguous () const
	If matrix indices are packed into single array (done in OptimizeStorage()) return true, otherwise false.
bool	LowerTriangular () const
	If matrix is lower triangular in local index space, this query returns true, otherwise it returns false.
bool	UpperTriangular () const
	If matrix is upper triangular in local index space, this query returns true, otherwise it returns false.
bool	NoDiagonal () const
	If matrix has no diagonal entries in global index space, this query returns true, otherwise it returns false.
Atribute access functions
double	NormInf () const
	Returns the infinity norm of the global matrix.
double	NormOne () const
	Returns the one norm of the global matrix.
int	NumGlobalNonzeros () const
	Returns the number of nonzero entries in the global matrix.
int	NumGlobalRows () const
	Returns the number of global matrix rows.
int	NumGlobalCols () const
	Returns the number of global matrix columns.
int	NumGlobalDiagonals () const
	Returns the number of global nonzero diagonal entries, based on global row/column index comparisons.
int	NumMyNonzeros () const
	Returns the number of nonzero entries in the calling processor's portion of the matrix.
int	NumMyRows () const
	Returns the number of matrix rows owned by the calling processor.
int	NumMyCols () const
	Returns the number of entries in the set of column-indices that appear on this processor.
int	NumMyDiagonals () const
	Returns the number of local nonzero diagonal entries, based on global row/column index comparisons.
int	NumGlobalEntries (int Row) const
	Returns the current number of nonzero entries in specified global row on this processor.
int	NumAllocatedGlobalEntries (int Row) const
	Returns the allocated number of nonzero entries in specified global row on this processor.
int	MaxNumEntries () const
	Returns the maximum number of nonzero entries across all rows on this processor.
int	GlobalMaxNumEntries () const
	Returns the maximum number of nonzero entries across all rows on all processors.
int	NumMyEntries (int Row) const
	Returns the current number of nonzero entries in specified local row on this processor.
int	NumAllocatedMyEntries (int Row) const
	Returns the allocated number of nonzero entries in specified local row on this processor.
int	IndexBase () const
	Returns the index base for row and column indices for this graph.
bool	StaticGraph ()
	Returns true if the graph associated with this matrix was pre-constructed and therefore not changeable.
const Epetra_CrsGraph &	Graph () const
	Returns a reference to the Epetra_CrsGraph object associated with this matrix.
const Epetra_Map &	RowMap () const
	Returns the Epetra_Map object associated with the rows of this matrix.
int	ReplaceRowMap (const Epetra_BlockMap &newmap)
	Replaces the current RowMap with the user-specified map object.
bool	HaveColMap () const
	Returns true if we have a well-defined ColMap, and returns false otherwise.
int	ReplaceColMap (const Epetra_BlockMap &newmap)
	Replaces the current ColMap with the user-specified map object.
const Epetra_Map &	ColMap () const
	Returns the Epetra_Map object that describes the set of column-indices that appear in each processor's locally owned matrix rows.
const Epetra_Map &	DomainMap () const
	Returns the Epetra_Map object associated with the domain of this matrix operator.
const Epetra_Map &	RangeMap () const
	Returns the Epetra_Map object associated with the range of this matrix operator.
const Epetra_Import *	Importer () const
	Returns the Epetra_Import object that contains the import operations for distributed operations.
const Epetra_Export *	Exporter () const
	Returns the Epetra_Export object that contains the export operations for distributed operations.
const Epetra_Comm &	Comm () const
	Returns a pointer to the Epetra_Comm communicator associated with this matrix.
Local/Global ID methods
int	LRID (int GRID) const
	Returns the local row index for given global row index, returns -1 if no local row for this global row.
int	GRID (int LRID) const
	Returns the global row index for give local row index, returns IndexBase-1 if we don't have this local row.
int	LCID (int GCID) const
	Returns the local column index for given global column index, returns -1 if no local column for this global column.
int	GCID (int LCID) const
	Returns the global column index for give local column index, returns IndexBase-1 if we don't have this local column.
bool	MyGRID (int GRID) const
	Returns true if the GRID passed in belongs to the calling processor in this map, otherwise returns false.
bool	MyLRID (int LRID) const
	Returns true if the LRID passed in belongs to the calling processor in this map, otherwise returns false.
bool	MyGCID (int GCID) const
	Returns true if the GCID passed in belongs to the calling processor in this map, otherwise returns false.
bool	MyLCID (int LCID) const
	Returns true if the LRID passed in belongs to the calling processor in this map, otherwise returns false.
bool	MyGlobalRow (int GID) const
	Returns true of GID is owned by the calling processor, otherwise it returns false.
I/O Methods.
virtual void	Print (ostream &os) const
	Print method.
Additional methods required to support the Epetra_Operator interface.
const char *	Label () const
	Returns a character string describing the operator.
int	SetUseTranspose (bool UseTranspose)
	If set true, transpose of this operator will be applied.
int	Apply (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_Operator applied to a Epetra_MultiVector X in Y.
int	ApplyInverse (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Returns the result of a Epetra_Operator inverse applied to an Epetra_MultiVector X in Y.
bool	HasNormInf () const
	Returns true because this class can compute an Inf-norm.
bool	UseTranspose () const
	Returns the current UseTranspose setting.
const Epetra_Map &	OperatorDomainMap () const
	Returns the Epetra_Map object associated with the domain of this matrix operator.
const Epetra_Map &	OperatorRangeMap () const
	Returns the Epetra_Map object associated with the range of this matrix operator.
Additional methods required to implement Epetra_RowMatrix interface.
int	NumMyRowEntries (int MyRow, int &NumEntries) const
	Return the current number of values stored for the specified local row.
const Epetra_Map &	RowMatrixRowMap () const
	Returns the Epetra_Map object associated with the rows of this matrix.
const Epetra_Map &	RowMatrixColMap () const
	Returns the Epetra_Map object associated with columns of this matrix.
const Epetra_Import *	RowMatrixImporter () const
	Returns the Epetra_Import object that contains the import operations for distributed operations.
Inlined Operator Methods.
double *	operator[] (int Loc)
	Inlined bracket operator for fast access to data. (Const and Non-const versions).
double *	operator[] (int Loc) const
Expert-only methods: These methods are intended for experts only and have some risk of changing in the future, since they rely on underlying data structure assumptions.
int	ExtractCrsDataPointers (int *&IndexOffset, int *&Indices, double *&Values) const
	Returns internal data pointers associated with Crs matrix format.
Deprecated methods: These methods still work, but will be removed in a future version.
const Epetra_Map &	ImportMap () const
	Use ColMap() instead.
int	TransformToLocal ()
	Use FillComplete() instead.
int	TransformToLocal (const Epetra_Map *DomainMap, const Epetra_Map *RangeMap)
	Use FillComplete(const Epetra_Map& DomainMap, const Epetra_Map& RangeMap) instead.
Protected Member Functions
bool	Allocated () const
int	SetAllocated (bool Flag)
double **	Values () const
double *	All_Values () const
double *	Values (int LocalRow) const
void	InitializeDefaults ()
int	Allocate ()
int	InsertValues (int LocalRow, int NumEntries, double *Values, int *Indices)
int	InsertOffsetValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
int	ReplaceOffsetValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
int	SumIntoOffsetValues (int GlobalRow, int NumEntries, double *Values, int *Indices)
void	UpdateImportVector (int NumVectors) const
void	UpdateExportVector (int NumVectors) const
void	GeneralMV (double *x, double *y) const
void	GeneralMTV (double *x, double *y) const
void	GeneralMM (double **X, int LDX, double **Y, int LDY, int NumVectors) const
void	GeneralMTM (double **X, int LDX, double **Y, int LDY, int NumVectors) const
void	GeneralSV (bool Upper, bool Trans, bool UnitDiagonal, double *x, double *y) const
void	GeneralSM (bool Upper, bool Trans, bool UnitDiagonal, double **X, int LDX, double **Y, int LDY, int NumVectors) const
void	SetStaticGraph (bool Flag)
int	CheckSizes (const Epetra_SrcDistObject &A)
	Allows the source and target (this) objects to be compared for compatibility, return nonzero if not.
int	CopyAndPermute (const Epetra_SrcDistObject &Source, int NumSameIDs, int NumPermuteIDs, int *PermuteToLIDs, int *PermuteFromLIDs, const Epetra_OffsetIndex *Indexor)
	Perform ID copies and permutations that are on processor.
int	CopyAndPermuteCrsMatrix (const Epetra_CrsMatrix &A, int NumSameIDs, int NumPermuteIDs, int *PermuteToLIDs, int *PermuteFromLIDs, const Epetra_OffsetIndex *Indexor)
int	CopyAndPermuteRowMatrix (const Epetra_RowMatrix &A, int NumSameIDs, int NumPermuteIDs, int *PermuteToLIDs, int *PermuteFromLIDs, const Epetra_OffsetIndex *Indexor)
int	PackAndPrepare (const Epetra_SrcDistObject &Source, int NumExportIDs, int *ExportLIDs, int &LenExports, char *&Exports, int &SizeOfPacket, int *Sizes, bool &VarSizes, Epetra_Distributor &Distor)
	Perform any packing or preparation required for call to DoTransfer().
int	UnpackAndCombine (const Epetra_SrcDistObject &Source, int NumImportIDs, int *ImportLIDs, int LenImports, char *Imports, int &SizeOfPacket, Epetra_Distributor &Distor, Epetra_CombineMode CombineMode, const Epetra_OffsetIndex *Indexor)
	Perform any unpacking and combining after call to DoTransfer().
int	SortEntries ()
	Sort column entries, row-by-row, in ascending order.
bool	Sorted () const
	If SortEntries() has been called, this query returns true, otherwise it returns false.
int	MergeRedundantEntries ()
	Add entries that have the same column index. Remove redundant entries from list.
bool	NoRedundancies () const
	If MergeRedundantEntries() has been called, this query returns true, otherwise it returns false.
void	DeleteMemory ()
Protected Attributes
Epetra_CrsGraph	Graph_
bool	Allocated_
bool	StaticGraph_
bool	UseTranspose_
bool	constructedWithFilledGraph_
bool	matrixFillCompleteCalled_
bool	StorageOptimized_
double **	Values_
double *	All_Values_
double	NormInf_
double	NormOne_
int	NumMyRows_
Epetra_MultiVector *	ImportVector_
Epetra_MultiVector *	ExportVector_
Epetra_DataAccess	CV_
bool	squareFillCompleteCalled_

---

Detailed Description

Epetra_CrsMatrix: A class for constructing and using real-valued double-precision sparse compressed row matrices.

The Epetra_CrsMatrix class is a sparse compressed row matrix object. This matrix can be used in a parallel setting, with data distribution described by Epetra_Map attributes. The structure or graph of the matrix is defined by an Epetra_CrsGraph attribute.

In addition to coefficient access, the primary operations provided by Epetra_CrsMatrix are matrix times vector and matrix times multi-vector multiplication.

Epetra_CrsMatrix matrices can be square or rectangular.

Creating and filling Epetra_CrsMatrix objects

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

1. Create Epetra_CrsMatrix instance, including storage, via one of the constructors:
   • Constructor that accepts one Epetra_Map object, a row-map defining the distribution of matrix rows.
   • Constructor that accepts two Epetra_Map objects. (The second map is a column-map, and describes the set of column-indices that appear in each processor's portion of the matrix. Generally these are overlapping sets -- column-indices may appear on more than one processor.)
   • Constructor that accepts an Epetra_CrsGraph object, defining the non-zero structure of the matrix.
   Note that the constructors which accept Epetra_Map arguments also accept an argument that gives an estimate of the number of nonzeros per row. This allows storage to be pre-allocated and can improve the performance of the data input methods. The estimate need not be accurate, as additional storage is allocated automatically when needed. However, a more accurate estimate helps performance by reducing the amount of extra memory allocation.
2. Enter values via one or more Insert/Replace/SumInto functions.
3. Complete construction by calling FillComplete.

Note that, even after a matrix is constructed (FillComplete has been called), it is possible to update existing matrix entries. It is not possible to create new entries.

Epetra_Map attributes

Epetra_CrsMatrix objects have four Epetra_Map attributes, which are held by the Epetra_CrsGraph attribute.

The Epetra_Map attributes can be obtained via these accessor methods:

• RowMap() Describes the numbering and distribution of the rows of the matrix. The row-map exists and is valid for the entire life of the matrix. The set of matrix rows is defined by the row-map and may not be changed. Rows may not be inserted or deleted by the user. The only change that may be made is that the user can replace the row-map with a compatible row-map (which is the same except for re-numbering) by calling the ReplaceRowMap() method.
• ColMap() Describes the set of column-indices that appear in the rows in each processor's portion of the matrix. Unless provided by the user at construction time, a valid column-map doesn't exist until FillComplete() is called.
• RangeMap() Describes the range of the matrix operator. e.g., for a matrix-vector product operation, the result vector's map must be compatible with the range-map of this matrix. The range-map is usually the same as the row-map. The range-map is set equal to the row-map at matrix creation time, but may be specified by the user when FillComplete() is called.
• DomainMap() Describes the domain of the matrix operator. The domain-map can be specified by the user when FillComplete() is called. Until then, it is set equal to the row-map.

It is important to note that while the row-map and the range-map are often the same, the column-map and the domain-map are almost never the same. The set of entries in a distributed column-map almost always form overlapping sets, with entries being associated with more than one processor. A domain-map, on the other hand, must be a 1-to-1 map, with entries being associated with only a single processor.

Local versus Global Indices

Epetra_CrsMatrix has query functions IndicesAreLocal() and IndicesAreGlobal(), which are used to determine whether the underlying Epetra_CrsGraph attribute's column-indices have been transformed into a local index space or not. (This transformation occurs when the method Epetra_CrsGraph::FillComplete() is called, which happens when the method Epetra_CrsMatrix::FillComplete() is called.) The state of the indices in the graph determines the behavior of many Epetra_CrsMatrix methods. If an Epetra_CrsMatrix instance is constructed using one of the constructors that does not accept a pre-existing Epetra_CrsGraph object, then an Epetra_CrsGraph attribute is created internally and its indices remain untransformed (IndicesAreGlobal()==true) until Epetra_CrsMatrix::FillComplete() is called. The query function Epetra_CrsMatrix::Filled() returns true if Epetra_CrsMatrix::FillComplete() has been called.

Note the following method characteristics:

• InsertGlobalValues() may only be used to insert new nonzeros in the matrix if indices are global.
• SumIntoGlobalValues() may be used regardless of whether indices are global or local, but can only be used to update matrix locations that already exist; it can never be used to establish new nonzero locations.
• ReplaceGlobalValues() may also be used only to update matrix locations that already exist, and works regardless of whether indices are local or global.
• SumIntoMyValues() and ReplaceMyValues() may only be used if indices are local.
• Multiply() may only be used after FillComplete() has been called.

Most methods have preconditions documented, check documentation for specific methods not mentioned here.

Counting Floating Point Operations

Each Epetra_CrsMatrix object keeps track of the number of serial floating point operations performed using the specified object as the this argument to the function. The Flops() function returns this number as a double precision number. Using this information, in conjunction with the Epetra_Time class, one can get accurate parallel performance numbers. The ResetFlops() function resets the floating point counter.

Warning:

A Epetra_Map is required for the Epetra_CrsMatrix constructor.

---

Constructor & Destructor Documentation

Epetra_CrsMatrix::Epetra_CrsMatrix (  Epetra_DataAccess  CV, const Epetra_Map &  RowMap, const int *  NumEntriesPerRow, bool  StaticProfile = false )

Epetra_CrsMatrix constructor with variable number of indices per row. Creates a Epetra_CrsMatrix object and allocates storage. Parameters: CV  - (In) An Epetra_DataAccess enumerated type set to Copy or View. RowMap  - (In) An Epetra_Map defining the numbering and distribution of matrix rows. NumEntriesPerRow  - (In) An integer array of length NumRows such that NumEntriesPerRow[i] indicates the (approximate if StaticProfile=false) number of entries in the ith row. StaticProfile  - (In) Optional argument that indicates whether or not NumIndicesPerRow should be interpreted as an exact count of nonzeros, or should be used as an approximation. By default this value is false, allowing the profile to be determined dynamically. If the user sets it to true, then the memory allocation for the Epetra_CrsGraph object will be done in one large block, saving on memory fragmentation and generally improving the performance of matrix multiplication and solve kernels.

Epetra_CrsMatrix::Epetra_CrsMatrix (  Epetra_DataAccess  CV, const Epetra_Map &  RowMap, int  NumEntriesPerRow, bool  StaticProfile = false )

Epetra_CrsMatrix constructor with fixed number of indices per row. Creates a Epetra_CrsMatrix object and allocates storage. Parameters: CV  - (In) An Epetra_DataAccess enumerated type set to Copy or View. RowMap  - (In) An Epetra_Map defining the numbering and distribution of matrix rows. NumEntriesPerRow  - (In) An integer that indicates the (approximate) number of entries in the each row. Note that it is possible to use 0 for this value and let fill occur during the insertion phase. StaticProfile  - (In) Optional argument that indicates whether or not NumIndicesPerRow should be interpreted as an exact count of nonzeros, or should be used as an approximation. By default this value is false, allowing the profile to be determined dynamically. If the user sets it to true, then the memory allocation for the Epetra_CrsGraph object will be done in one large block, saving on memory fragmentation and generally improving the performance of matrix multiplication and solve kernels.

Epetra_CrsMatrix::Epetra_CrsMatrix (  Epetra_DataAccess  CV, const Epetra_Map &  RowMap, const Epetra_Map &  ColMap, const int *  NumEntriesPerRow, bool  StaticProfile = false )

Epetra_CrsMatrix constructor with variable number of indices per row. Creates a Epetra_CrsMatrix object and allocates storage. Parameters: CV  - (In) An Epetra_DataAccess enumerated type set to Copy or View. RowMap  - (In) An Epetra_Map defining the numbering and distribution of matrix rows. ColMap  - (In) An Epetra_Map defining the set of column-indices that appear in each processor's locally owned matrix rows. NumEntriesPerRow  - (In) An integer array of length NumRows such that NumEntriesPerRow[i] indicates the (approximate if StaticProfile=false) number of entries in the ith row. StaticProfile  - (In) Optional argument that indicates whether or not NumIndicesPerRow should be interpreted as an exact count of nonzeros, or should be used as an approximation. By default this value is false, allowing the profile to be determined dynamically. If the user sets it to true, then the memory allocation for the Epetra_CrsGraph object will be done in one large block, saving on memory fragmentation and generally improving the performance of matrix multiplication and solve kernels.

Epetra_CrsMatrix::Epetra_CrsMatrix (  Epetra_DataAccess  CV, const Epetra_Map &  RowMap, const Epetra_Map &  ColMap, int  NumEntriesPerRow, bool  StaticProfile = false )

Epetra_CrsMatrix constuctor with fixed number of indices per row. Creates a Epetra_CrsMatrix object and allocates storage. Parameters: CV  - (In) An Epetra_DataAccess enumerated type set to Copy or View. RowMap  - (In) An Epetra_Map defining the numbering and distribution of matrix rows. ColMap  - (In) An Epetra_Map defining the set of column-indices that appear in each processor's locally owned matrix rows. NumEntriesPerRow  - (In) An integer that indicates the (approximate if StaticProfile=false) number of entries in the each row. Note that it is possible to use 0 for this value and let fill occur during the insertion phase. StaticProfile  - (In) Optional argument that indicates whether or not NumIndicesPerRow should be interpreted as an exact count of nonzeros, or should be used as an approximation. By default this value is false, allowing the profile to be determined dynamically. If the user sets it to true, then the memory allocation for the Epetra_CrsGraph object will be done in one large block, saving on memory fragmentation and generally improving the performance of matrix multiplication and solve kernels.

Epetra_CrsMatrix::Epetra_CrsMatrix (  Epetra_DataAccess  CV, const Epetra_CrsGraph &  Graph )

Construct a matrix using an existing Epetra_CrsGraph object. Allows the nonzero structure from another matrix, or a structure that was constructed independently, to be used for this matrix. Parameters: CV  - (In) An Epetra_DataAccess enumerated type set to Copy or View. Graph  - (In) A Epetra_CrsGraph object, constructed directly or extracted from another Epetra matrix object.

---

Member Function Documentation

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

Returns the result of a Epetra_Operator applied to a Epetra_MultiVector X in Y. Parameters: X  - (In) An Epetra_MultiVector of dimension NumVectors to multiply with matrix. Y  -(Out) An Epetra_MultiVector of dimension NumVectors containing result. Returns: Integer error code, set to 0 if successful. Precondition: Filled()==true Postcondition: Unchanged. Implements Epetra_Operator.

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

Returns the result of a Epetra_Operator inverse applied to an Epetra_MultiVector X in Y. In this implementation, we use several existing attributes to determine how virtual method ApplyInverse() should call the concrete method Solve(). We pass in the UpperTriangular(), the Epetra_CrsMatrix::UseTranspose(), and NoDiagonal() methods. The most notable warning is that if a matrix has no diagonal values we assume that there is an implicit unit diagonal that should be accounted for when doing a triangular solve. Parameters: 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. Precondition: Filled()==true Postcondition: Unchanged. Implements Epetra_Operator.

const Epetra_Map& Epetra_CrsMatrix::ColMap (   )  const [inline]

Returns the Epetra_Map object that describes the set of column-indices that appear in each processor's locally owned matrix rows. Note that if the matrix was constructed with only a row-map, then until FillComplete() is called, this method returns a column-map that is a copy of the row-map. That 'initial' column-map is replaced with a computed column-map (that contains the set of column-indices appearing in each processor's local portion of the matrix) when FillComplete() is called. Precondition: HaveColMap()==true

const Epetra_Map& Epetra_CrsMatrix::DomainMap (   )  const [inline]

Returns the Epetra_Map object associated with the domain of this matrix operator. Precondition: Filled()==true

int Epetra_CrsMatrix::ExtractCrsDataPointers (  int *&  IndexOffset, int *&  Indices, double *&  Values )  const [inline]

Returns internal data pointers associated with Crs matrix format. Returns data pointers to facilitate optimized code within external packages. Parameters: IndexOffset  - (Out) Extracted array of indices into Values[] and Indices[]. Local row k is stored in Values[IndexOffset[k]:IndexOffset[k+1]-1] and Indices[IndexOffset[k]:IndexOffset[k+1]-1]. Values  - (Out) Extracted values for all local rows. Indices  - (Out) Extracted local column indices for the corresponding values. Returns: Integer error code, set to 0 if successful. Returns -1 if FillComplete has not been performed or Storage has not been Optimized. Warning: This method is intended for expert only, its use may require user code modifications in future versions of Epetra.

int Epetra_CrsMatrix::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. Precondition: Filled()==true Postcondition: Unchanged. Implements Epetra_RowMatrix.

int Epetra_CrsMatrix::ExtractGlobalRowCopy (  int  GlobalRow, int  Length, int &  NumEntries, double *  Values )  const

Returns a copy of the specified global row values in user-provided array. Parameters: GlobalRow  - (In) Global row to extract. Length  - (In) Length of Values. NumEntries  - (Out) Number of nonzero entries extracted. Values  - (Out) Extracted values for this row. Returns: Integer error code, set to 0 if successful.

int Epetra_CrsMatrix::ExtractGlobalRowCopy (  int  GlobalRow, int  Length, int &  NumEntries, double *  Values, int *  Indices )  const

Returns a copy of the specified global row in user-provided arrays. Parameters: GlobalRow  - (In) Global row to extract. ILength  - (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, non-zero if global row is not owned by calling process or if the number of entries in this row exceed the Length parameter.

int Epetra_CrsMatrix::ExtractGlobalRowView (  int  GlobalRow, int &  NumEntries, double *&  Values )  const

Returns a view of the specified global row values via pointers to internal data. Parameters: GlobalRow  - (In) Global row to extract. NumEntries  - (Out) Number of nonzero entries extracted. Values  - (Out) Extracted values for this row. Returns: Integer error code, set to 0 if successful.

int Epetra_CrsMatrix::ExtractGlobalRowView (  int  GlobalRow, int &  NumEntries, double *&  Values, int *&  Indices )  const

Returns a view of the specified global row values via pointers to internal data. Parameters: GlobalRow  - (In) Global row to view. 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. Returns -1 of row not on this processor. Returns -2 if matrix is not in global form (if FillComplete() has already been called). Precondition: IndicesAreGlobal()==true

int Epetra_CrsMatrix::ExtractMyRowCopy (  int  MyRow, int  Length, int &  NumEntries, double *  Values )  const

Returns a copy of the specified local row values in user-provided array. Parameters: MyRow  - (In) Local row to extract. Length  - (In) Length of Values. NumEntries  - (Out) Number of nonzero entries extracted. Values  - (Out) Extracted values for this row. Returns: Integer error code, set to 0 if successful.

int Epetra_CrsMatrix::ExtractMyRowCopy (  int  MyRow, int  Length, int &  NumEntries, double *  Values, int *  Indices )  const [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 local column indices for the corresponding values. Returns: Integer error code, set to 0 if successful. Precondition: IndicesAreLocal()==true Implements Epetra_RowMatrix.

int Epetra_CrsMatrix::ExtractMyRowView (  int  MyRow, int &  NumEntries, double *&  Values )  const

Returns a view of the specified local row values via pointers to internal data. Parameters: MyRow  - (In) Local row to extract. NumEntries  - (Out) Number of nonzero entries extracted. Values  - (Out) Extracted values for this row. Returns: Integer error code, set to 0 if successful.

int Epetra_CrsMatrix::ExtractMyRowView (  int  MyRow, int &  NumEntries, double *&  Values, int *&  Indices )  const

Returns a view of the specified local row values via pointers to internal data. Parameters: MyRow  - (In) Local row to view. NumEntries  - (Out) Number of nonzero entries extracted. Values  - (Out) Extracted values for this row. Indices  - (Out) Extracted local column indices for the corresponding values. Returns: Integer error code, set to 0 if successful. Returns -1 of row not on this processor. Returns -2 if matrix is not in local form (if FillComplete() has not been called). Precondition: IndicesAreLocal()==true

int Epetra_CrsMatrix::GCID (  int  LCID  )  const [inline]

Returns the global column index for give local column index, returns IndexBase-1 if we don't have this local column. Precondition: HaveColMap()==true (If HaveColMap()==false, returns -1)

int Epetra_CrsMatrix::GlobalMaxNumEntries (   )  const [inline]

Returns the maximum number of nonzero entries across all rows on all processors. Precondition: Filled()==true

bool Epetra_CrsMatrix::HaveColMap (   )  const [inline]

Returns true if we have a well-defined ColMap, and returns false otherwise. Precondition: We have a well-defined ColMap if a) a ColMap was passed in at construction, or b) the MakeColMap function has been called. (Calling either of the FillComplete functions will result in MakeColMap being called.)

int Epetra_CrsMatrix::InsertGlobalValues (  int  GlobalRow, int  NumEntries, double *  Values, int *  Indices )