Epetra_OskiMatrix: A class for constructing and using OSKI Matrices within Epetra. For information on known issues with OSKI see the detailed description. More...

#include <Epetra_OskiMatrix.h>

Inheritance diagram for Epetra_OskiMatrix:

[legend]

Collaboration diagram for Epetra_OskiMatrix:

[legend]

List of all members.

Public Member Functions
Constructors/Destructor
	Epetra_OskiMatrix (const Epetra_OskiMatrix &Source)
	Copy constructor.
	Epetra_OskiMatrix (const Epetra_CrsMatrix &Source, const Teuchos::ParameterList &List)
	Constructor creates an Epetra_OskiMatrix from an Epetra_CrsMatrix.
virtual	~Epetra_OskiMatrix ()
	Destructor.
Extract/Replace Values
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. Warning this could be expensive.
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. WARNING: this could be expensive.
int	ExtractDiagonalCopy (Epetra_Vector &Diagonal) const
	Returns a copy of the main diagonal in a user-provided vector.
int	ReplaceDiagonalValues (const Epetra_OskiVector &Diagonal)
	Replaces diagonal values of the matrix with those in the user-provided vector.
Computational methods
int	Multiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y) const
	Performs a matrix vector multiply of y = this^TransA*x.
int	Multiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y, double Alpha, double Beta=0.0) const
	Performs a matrix vector multiply of y = Alphathis^TransAx + Beta*y.
int	Multiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Performs a matrix multi-vector multiply of Y = this^TransA*X.
int	Multiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y, double Alpha, double Beta=0.0) const
	Performs a matrix multi-vector multiply of Y = Alphathis^TransAX + Beta*Y.
int	Solve (bool Upper, bool TransA, bool UnitDiagonal, const Epetra_Vector &x, Epetra_Vector &y) const
	Performs a triangular solve of y = (this^TransA)^-1*x where this is a triangular matrix.
int	Solve (bool TransA, const Epetra_Vector &x, Epetra_Vector &y, double Alpha=1.0) const
	Performs a triangular solve of y = Alpha(this^TransA)^-1x where this is a triangular matrix.
int	Solve (bool Upper, bool TransA, bool UnitDiagonal, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Performs a triangular solve of Y = (this^TransA)^-1*X where this is a triangular matrix.
int	Solve (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y, double Alpha=1.0) const
	Performs a triangular solve of Y = Alpha(this^TransA)^-1X where this is a triangular matrix.
int	MatTransMatMultiply (bool ATA, const Epetra_Vector &x, Epetra_Vector &y, Epetra_Vector *t, double Alpha=1.0, double Beta=0.0) const
	Performs two matrix vector multiplies of y = Alphathis^TransAthisx + Betay or y = Alphathisthis^TransAx + Betay.
int	MatTransMatMultiply (bool ATA, const Epetra_MultiVector &X, Epetra_MultiVector &Y, Epetra_MultiVector *T, double Alpha=1.0, double Beta=0.0) const
	Performs two matrix multi-vector multiplies of Y = Alphathis^TransAthisX + BetaY or Y = Alphathisthis^TransAX + BetaY.
int	MultiplyAndMatTransMultiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y, const Epetra_Vector &w, Epetra_Vector &z, double Alpha=1.0, double Beta=0.0, double Omega=1.0, double Zeta=0.0) const
	Performs the two matrix vector multiplies of y = Alphathisx + Betay and z = Omegathis^TransAw + Zetaz.
int	MultiplyAndMatTransMultiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y, const Epetra_MultiVector &W, Epetra_MultiVector &Z, double Alpha=1.0, double Beta=0.0, double Omega=1.0, double Zeta=0.0) const
	Performs the two matrix multi-vector multiplies of Y = AlphathisX + BetaY and Z = Omegathis^TransAW + ZetaZ.
int	MatPowMultiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y, Epetra_MultiVector &T, int Power=2, double Alpha=1.0, double Beta=0.0) const
	Performs a matrix vector multiply of y = Alpha(this^TransA)^Powerx + Beta*y. This is not implemented as described in the detailed description.
int	MatPowMultiply (bool TransA, const Epetra_Vector &x, Epetra_Vector &y, int Power=2, double Alpha=1.0, double Beta=0.0) const
	Performs a matrix vector multiply of y = Alpha(this^TransA)^Powerx + Beta*y. This is not implemented as described in the detailed description.
Tuning
int	SetHint (const Teuchos::ParameterList &List)
	Stores the hints in List in the matrix structure.
int	SetHintMultiply (bool TransA, double Alpha, const Epetra_OskiMultiVector &InVec, double Beta, const Epetra_OskiMultiVector &OutVec, int NumCalls, const Teuchos::ParameterList &List)
	Workload hints for computing a matrix-vector multiply used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.
int	SetHintSolve (bool TransA, double Alpha, const Epetra_OskiMultiVector &Vector, int NumCalls, const Teuchos::ParameterList &List)
	Workload hints for computing a triangular solve used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.
int	SetHintMatTransMatMultiply (bool ATA, double Alpha, const Epetra_OskiMultiVector &InVec, double Beta, const Epetra_OskiMultiVector &OutVec, const Epetra_OskiMultiVector &Intermediate, int NumCalls, const Teuchos::ParameterList &List)
	Workload hints for computing a two matrix-vector multiplies that are composed used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.
int	SetHintMultiplyAndMatTransMultiply (bool TransA, double Alpha, const Epetra_OskiMultiVector &InVec, double Beta, const Epetra_OskiMultiVector &OutVec, double Omega, const Epetra_OskiMultiVector &InVec2, double Zeta, const Epetra_OskiMultiVector &OutVec2, int NumCalls, const Teuchos::ParameterList &List)
	Workload hints for computing two matrix-vector multiplies used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.
int	SetHintPowMultiply (bool TransA, double Alpha, const Epetra_OskiMultiVector &InVec, double Beta, const Epetra_OskiMultiVector &OutVec, const Epetra_OskiMultiVector &Intermediate, int Power, int NumCalls, const Teuchos::ParameterList &List)
	Workload hints for computing a matrix-vector multiply performed Power times used by OskiTuneMat to optimize the data structure storage and the routine to compute the calculation.
int	TuneMatrix ()
	Tunes the matrix multiply if its deemed profitable.
Data Structure Transformation Methods
int	IsMatrixTransformed () const
	Returns 1 if the matrix has been reordered by tuning, and 0 if it has not been.
const Epetra_OskiMatrix &	ViewTransformedMat () const
	Returns the transformed version of InMat if InMat has been transformed. If InMat has not been transformed then the return will equal InMat.
const Epetra_OskiPermutation &	ViewRowPermutation () const
	Returns a read only row/left permutation of the Matrix.
const Epetra_OskiPermutation &	ViewColumnPermutation () const
	Returns a read only column/right permutation of the Matrix.
char *	GetMatrixTransforms () const
	Returns a string holding the transformations performed on the matrix when it was tuned.
int	ApplyMatrixTransforms (const char *Transforms)
	Replaces the current data structure of the matrix with the one specified in Transforms.

Detailed Description

Epetra_OskiMatrix: A class for constructing and using OSKI Matrices within Epetra. For information on known issues with OSKI see the detailed description.

OSKI is a high-performance sparse matrix kernel package written by the UC Berkeley Benchmarking and Optimization Group. The Epetra_OskiMatrix class is a lightweight interface to allow Epetra users access to OSKI functionality. This interface includes lightweight conversion of Epetra matrices to OSKI matrices, runtime tuning based on parameter list hints, and access to high-performance computational kernels to perform matrix-vector/matrix multi-vector calculations.

The Epetra_OskiMatrix class provides access to the entire OSKI interface. However, the following features are not fully implemented in OSKI version oski-1.0.1h, and therefore are unsupported in the Epetra_OskiMatrix class:

OSKI does not provide stock composed kernels. Hence, the tune function must be called in order to see performance gains when using the MatTransMatMultiply and MultiplyAndMatTransMultiply kernels.
The MatPowMultiply kernel does not work.
Optimized multivector kernels are not created by default when installing OSKI.
The tune function cannot transform a (nearly) symmetric matrix to be stored as such.

In order to use the $A^TA$

OSKI kernel (MatTransMatMultiply), in oski/src/MBCSR/ata.c you must replace the lines

 const char *kernel_name = (opA == OP_AT_A)
        ? "SubmatRperTransSubmatRperMult" : "SubmatRperHermSubmatRperMult";

with

 const char *kernel_name = (opA == OP_AT_A)
        ? "SubmatReprTransSubmatReprMult" : "SubmatReprHermSubmatReprMult";

OSKI does not convert between CSR and CSC when it could be profitable, such as when performing on a CSR matrix.
OSKI may be incompatible with the following architectures:
- Barcelona (quad-core Opteron): errors during "make install" (confirmed with OSKI developers)
- single core Xeon: OSKI installs, but never transforms matrices. This includes cases where other machines will transform the same matrices, and where one would expect the matrix to be transformed, based on OSKI tuning data.

Constructor & Destructor Documentation

Epetra_OskiMatrix::Epetra_OskiMatrix	(	const Epetra_CrsMatrix &	Source,
		const Teuchos::ParameterList &	List
	)

Constructor creates an Epetra_OskiMatrix from an Epetra_CrsMatrix.

Parameters:

Source	(In) An Epetra_CrsMatrix that is to be wrapped as an Epetra_OskiMatrix.
List	(In) Any options or data wanted or needed for the conversion.

Returns:: Pointer to an Epetra_OskiMatrix.

Options that can be passed to the List are presented below. They are: "<type> <option name> <default value>: <description of purpose>"

bool autotune false: If true, Epetra tries to set as many hints as possible based on its knowledge of the matrix.

string matrixtype general: Other types that can be taken are: uppertri, lowertri, uppersymm, lowersymm, fullsymm, upperherm, lowerherm and fullherm.

bool diagstored false: If true, the diagonal entries are not stored in the matrix and are all assumed to be 1.

bool zerobased false: If true, the array is zero based, as in C. Otherwise, it is 1 based, as in Fortran.

bool sorted false: If true, all elements in the passed in array are sorted.
bool unique false: If true, a value in a column only appears once in each row.
bool deepcopy false: If true, when the OSKI matrix is created it will be a deepcopy of the data in the function.

Member Function Documentation

int Epetra_OskiMatrix::ApplyMatrixTransforms ( const char * Transforms )

Replaces the current data structure of the matrix with the one specified in Transforms.

If a previously tuned copy of the Matrix existed it is now replaced by one specified in Transforms.

Parameters:

Transforms (In) A string that holds the transformations to be applied to the matrix. If Transforms is NULL or the empty string then no changes to the data structure are made.

Returns:: If the transformation was successful 0 is returned. Otherwise an error code is returned.

int Epetra_OskiMatrix::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 and non-zero if not.

Precondition:: Filled()==true

Postcondition:: Unchanged.

Reimplemented from Epetra_CrsMatrix.

char* Epetra_OskiMatrix::GetMatrixTransforms ( ) const

Returns a string holding the transformations performed on the matrix when it was tuned.

Returns:: Upon success returns a newly-allocated string that stores the transformations applied to the matrix during tuning. NULL is returned upon an error. It is the users responsibility to deallocate the returned string.

int Epetra_OskiMatrix::MatPowMultiply	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		Epetra_MultiVector &	T,
		int	Power = `2`,
		double	Alpha = `1.0`,
		double	Beta = `0.0`
	)		const

Performs a matrix vector multiply of y = Alpha*(this^TransA)^Power*x + Beta*y. This is not implemented as described in the detailed description.

The vectors x and y can be either Epetra_Vectors or Epetra_OskiVectors. The vector T can be either an Epetra_MultiVector or Epetra_OskiMultiVector. This composed routine is used in power and S-step methods. This routine is not implemented due a bug in the oski-1.01h kernel that makes testing of correctness impossible.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the product.
x	(In) The vector the matrix is multiplied by.
y	(In/Out) The vector where the calculation result is stored.
T	(Out) The multi-vector where the result of each subsequent multiplication thisx ... this^(Power-1)x is stored.
Power	(In) The power to raise the matrix to in the calculation.
Alpha	(In) A scalar constant used to scale x.
Beta	(In) A scalar constant used to scale y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::MatPowMultiply	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		int	Power = `2`,
		double	Alpha = `1.0`,
		double	Beta = `0.0`
	)		const

Performs a matrix vector multiply of y = Alpha*(this^TransA)^Power*x + Beta*y. This is not implemented as described in the detailed description.

The vectors x and y can be either Epetra_Vectors or Epetra_OskiVectors. This composed routine is used in power and S-step methods. This routine is not implemented due a bug in the oski-1.01h kernel that makes testing of correctness impossible.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the product.
x	(In) The vector the matrix is multiplied by.
y	(In/Out) The vector where the calculation result is stored.
Power	(In) The power to raise the matrix to in the calculation.
Alpha	(In) A scalar constant used to scale x.
Beta	(In) A scalar constant used to scale y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::MatTransMatMultiply	(	bool	ATA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		Epetra_Vector *	t,
		double	Alpha = `1.0`,
		double	Beta = `0.0`
	)		const

Performs two matrix vector multiplies of y = Alpha*this^TransA*this*x + Beta*y or y = Alpha*this*this^TransA*x + Beta*y.

The vectors x, y and t can be either Epetra_Vectors or Epetra_OskiVectors. This composed routine is most commonly used in linear least squares and bidiagonalization methods. The parallel version of y = Alpha*this*this^TransA*x + Beta*y uses calls to the Multiply routine under the hood, as it is not possible to perform both multiplies automatically.

Parameters:

ATA	(In) If TransA = TRUE then compute this^Tthisx otherwise compute thisthis^Tx.
x	(In) The vector the matrix is multiplied by.
y	(In/Out) The vector where the calculation result is stored.
t	(Out) The vector where the result of the thisx is stored if TransA = true and this^Tx is stored otherwise.
Alpha	(In) A scalar constant used to scale x.
Beta	(In) A scalar constant used to scale y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::MatTransMatMultiply	(	bool	ATA,
		const Epetra_MultiVector &	X,
		Epetra_MultiVector &	Y,
		Epetra_MultiVector *	T,
		double	Alpha = `1.0`,
		double	Beta = `0.0`
	)		const

Performs two matrix multi-vector multiplies of Y = Alpha*this^TransA*this*X + Beta*Y or Y = Alpha*this*this^TransA*X + Beta*Y.

The multi-vectors X, Y and T can be either Epetra_MultiVectors or Epetra_OskiMultiVectors. This composed routine is most commonly used in linear least squares and bidiagonalization methods. The parallel version of Y = Alpha*this*this^TransA*X + Beta*Y uses calls to the Multiply routine under the hood, as it is not possible to perform both multiplies automatically.

Parameters:

ATA	(In) If TransA = TRUE then compute this^TthisX otherwise compute thisthis^TX.
X	(In) The vector the matrix is multiplied by.
Y	(In/Out) The vector where the calculation result is stored.
T	(Out) The multi-vector where the result of the thisX is stored if TransA = true and this^TX is stored otherwise.
Alpha	(In) A scalar constant used to scale X.
Beta	(In) A scalar constant used to scale Y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::Multiply	(	bool	TransA,
		const Epetra_MultiVector &	X,
		Epetra_MultiVector &	Y,
		double	Alpha,
		double	Beta = `0.0`
	)		const

Performs a matrix multi-vector multiply of Y = Alpha*this^TransA*X + Beta*Y.

The multi-vectors X and Y can be either Epetra_MultiVectors or Epetra_OskiMultiVectors.

Parameters:

TransA	(In) If Trans = TRUE then use the transpose of the matrix in computing the product.
X	(In) The multi-vector the matrix is multiplied by.
Y	(In/Out) The multi-vector where the calculation result is stored.
Alpha	(In) A scalar constant used to scale X.
Beta	(In) A scalar constant used to scale Y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::Multiply	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y
	)		const

Performs a matrix vector multiply of y = this^TransA*x.

The vectors x and y can be either Epetra_Vectors or Epetra_OskiVectors.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the product.
x	(In) The vector the matrix is multiplied by.
y	(Out) The vector where the calculation result is stored.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

Reimplemented from Epetra_CrsMatrix.

int Epetra_OskiMatrix::Multiply	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		double	Alpha,
		double	Beta = `0.0`
	)		const

Performs a matrix vector multiply of y = Alpha*this^TransA*x + Beta*y.

The vectors x and y can be either Epetra_Vectors or Epetra_OskiVectors.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the product.
x	(In) The vector the matrix is multiplied by.
y	(In/Out) The vector where the calculation result is stored.
Alpha	(In) A scalar constant used to scale x.
Beta	(In) A scalar constant used to scale y.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

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

Performs a matrix multi-vector multiply of Y = this^TransA*X.

The multi-vectors X and Y can be either Epetra_MultiVectors or Epetra_OskiMultiVectors.

Parameters:

TransA	(In) If Trans = TRUE then use the transpose of the matrix in computing the product.
X	(In) The multi-vector the matrix is multiplied by.
Y	(Out) The multi-vector where the calculation result is stored.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

Reimplemented from Epetra_CrsMatrix.

int Epetra_OskiMatrix::MultiplyAndMatTransMultiply	(	bool	TransA,
		const Epetra_MultiVector &	X,
		Epetra_MultiVector &	Y,
		const Epetra_MultiVector &	W,
		Epetra_MultiVector &	Z,
		double	Alpha = `1.0`,
		double	Beta = `0.0`,
		double	Omega = `1.0`,
		double	Zeta = `0.0`
	)		const

Performs the two matrix multi-vector multiplies of Y = Alpha*this*X + Beta*Y and Z = Omega*this^TransA*W + Zeta*Z.

The multi-vectors X, Y, W and Z can be either Epetra_MultiVectors or Epetra_OskiMultiVectors. This composed routine is most commonly used in bi-conjugate gradient calculations.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the second product.
X	(In) A multi-vector the matrix is multiplied by.
Y	(In/Out) A multi-vector where the calculation result of the first multiply is stored.
W	(In) A multi-vector the matrix is multiplied by.
Z	(In/Out) A multi-vector where the calculation result of the second multiply is stored.
Alpha	(In) A scalar constant used to scale X.
Beta	(In) A scalar constant used to scale Y.
Omega	(In) A scalar constant used to scale W.
Zeta	(In) A scalar constant used to scale Z.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::MultiplyAndMatTransMultiply	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		const Epetra_Vector &	w,
		Epetra_Vector &	z,
		double	Alpha = `1.0`,
		double	Beta = `0.0`,
		double	Omega = `1.0`,
		double	Zeta = `0.0`
	)		const

Performs the two matrix vector multiplies of y = Alpha*this*x + Beta*y and z = Omega*this^TransA*w + Zeta*z.

The vectors x, y, w and z can be either Epetra_Vectors or Epetra_OskiVectors. This composed routine is most commonly used in bi-conjugate gradient calculations.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in computing the second product.
x	(In) A vector the matrix is multiplied by.
y	(In/Out) A vector where the calculation result of the first multiply is stored.
w	(In) A vector the matrix is multiplied by.
z	(In/Out) A vector where the calculation result of the second multiply is stored.
Alpha	(In) A scalar constant used to scale x.
Beta	(In) A scalar constant used to scale y.
Omega	(In) A scalar constant used to scale w.
Zeta	(In) A scalar constant used to scale z.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::ReplaceDiagonalValues ( const Epetra_OskiVector & Diagonal )

Replaces diagonal values of the matrix with those in the user-provided vector.

This routine is meant to allow replacement of { existing} diagonal values. If a diagonal value does not exist for a given row, the corresponding value in the input Epetra_OskiVector will be ignored, and the return code will be set to 1.

Parameters:

Diagonal - (In) New values to be placed in the main diagonal.

Returns:: Integer error code, set to 0 if successful, set to 1 on the calling processor if one or more diagonal entries not present in matrix. Other error codes can be returned as well, indicating improperly constructed matrices or vectors.

Precondition:: Filled()==true

Postcondition:: Diagonal values have been replaced with the values of Diagonal.

int Epetra_OskiMatrix::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. Warning this could be expensive.

The reason this function could be expensive is its underlying implementation. Both the OSKI and Epetra versions of the matrix must be changed when the matrix has been permuted. When this is the case, a call must be made to the Epetra ReplaceMyValues, and NumEntries calls must be made to a function that changes the OSKI matrix's values one at a time.

Parameters:

MyRow	(In) Row number (in local coordinates) to put elements.
NumEntries	(In) Number of entries.
Values	(In) Values to enter.
Indices	(In) Local column indices corresponding to the values.

Returns:: Integer error code, set to 0 if successful. Note that if the allocated length of the row has to be expanded, Oski will fail. A positive warning code may be returned, but this should be treated as a fatal error; part of the data will be changed, and OSKI cannot support adding in new data values.

Precondition:: IndicesAreLocal()==true

Postcondition:: The given Values at the given Indices have been summed into the entries of MyRow.

int Epetra_OskiMatrix::SetHint ( const Teuchos::ParameterList & List )

Stores the hints in List in the matrix structure.

Parameters:

List	(In) A list of hints and options to register along with the matrix used for tuning purposes. The full list is given below. It may be moved to the user guide in the future.

Returns:: On successful storage of the hint 0 is returned. On failure an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix. For options where multiple arguments can be passed in at once the interface only supports up to 5. This means only 5 block sizes or 5 diaganols can be passed in at once. If you have more changing the code to support your needs should be simple, but every case you use must be enumerated. Of course you can just say there are diagonals and blocks and not pass in specific sizes as wells.

bool noblocks: If true, the matrix has no block structure
bool singleblocksize: If true, the matrix structure is dominated by blocks of the size of the next two parameters.
- int row: The number of rows in each block.
- int col: The number of columns in each block.
bool multipleblocksize: If true, the matrix consists of multiple block sizes. The next 3 parameters describe these and are optional.
- int blocks: The number of block sizes in the matrix.
- int row<x>: Where x is the block number, and x goes from 1 to blocks. This is the number of rows in block x.
- int col<x>: Where x is the block number, and x goes from 1 to blocks. This is the number of cols in block x.

bool alignedblocks: If true, all blocks are aligned to a grid.
bool unalignedblocks: If true, blocks are not aligned to a grid.

bool symmetricpattern: If true, the matrix is either symmetric or nearly symmetric.
bool nonsymmetricpattern: If true, the matrix has a very unsymmetric pattern.

bool randompattern: If true, the matrix's non-zeros are distributed in a random pattern.
bool correlatedpattern: If true, the row and column indices for non-zeros are highly correlated.

bool nodiags : If true, the matrix has little or no diagonal structure.
bool diags: If true, the matrix consists of diagonal structure described the next two optional parameters.
- int numdiags: The number of diagonal sizes known to be present others not listed could be present.

int diag<x>: Where x is the diagonal number, and x goes from 1 to numdiags. This is the size of the diagonal.

int Epetra_OskiMatrix::SetHintMatTransMatMultiply	(	bool	ATA,
		double	Alpha,
		const Epetra_OskiMultiVector &	InVec,
		double	Beta,
		const Epetra_OskiMultiVector &	OutVec,
		const Epetra_OskiMultiVector &	Intermediate,
		int	NumCalls,
		const Teuchos::ParameterList &	List
	)

Workload hints for computing a two matrix-vector multiplies that are composed used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.

In parallel the routine uses symbolic vectors. This is done for two reasons. Doing this saves on data allocation and potentially communication overhead. For a matrix-vector routine there should be no advantage to having the actual vector, as its size must be the same as a matrix dimension. For a matrix-multivector routine there could be gains from knowing the number of vectors in the multi-vector. However, OSKI does not perform multi-vector optimizations, so there is no need to add the overhead.

Parameters:

ATA	(In) If ATA = true then this^Tthisx will be computed otherwise thisthis^Tx will be.
Alpha	(In) A scalar constant used to scale InVec.
InVec	(In) The vector the matrix is multiplied by or whether it is a single vector or multi-vector.
Beta	(In) A scalar constant used to scale OutVec.
OutVec	(In) The vector where the calculation result is stored or whether it is a single vector or multi-vector.
Intermediate	(In) The vector where result of the first product can be stored or whether it is a single vector or multi-vector. If this quantity is NULL then the intermediate product is not stored.
NumCalls	(In) The number of times the operation is called or the tuning level wanted.
List	(In) Used for denoting the use of symbolic vectors for InVec, OutVec and Intermediate, along with the level of aggressive tuning if either NumCalls not known or to be overridden. Options are shown below. It should be noted that by using these options the associated vector or NumCalls becomes invalid.

Returns:: Stores the workload hint in the matrix if the operation is valid. If the operation is not valid an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix.

These replace InVec.

bool symminvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symminmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace OutVec.

bool symmoutvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmoutmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace Intermediate.

bool symmintervec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmintermultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

bool tune: If true, have OSKI tune moderately rather than using the number of calls passed in.
bool tuneaggressive: If true, have OSKI tune aggressively rather than using the number of calls passed in.

int Epetra_OskiMatrix::SetHintMultiply	(	bool	TransA,
		double	Alpha,
		const Epetra_OskiMultiVector &	InVec,
		double	Beta,
		const Epetra_OskiMultiVector &	OutVec,
		int	NumCalls,
		const Teuchos::ParameterList &	List
	)

Workload hints for computing a matrix-vector multiply used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.

In parallel the routine uses symbolic vectors. This is done for two reasons. Doing this saves on data allocation and potentially communication overhead. For a matrix-vector routine there should be no advantage to having the actual vector, as its size must be the same as a matrix dimension. For a matrix-multivector routine there could be gains from knowing the number of vectors in the multi-vector. However, OSKI does not perform multi-vector optimizations, so there is no need to add the overhead.

Parameters:

Trans	(In) If Trans = true then the transpose of the matrix will be used in computing the product.
Alpha	(In) A scalar constant used to scale InVec.
InVec	(In) The vector the matrix is multiplied by or whether it is a single vector or multi-vector.
Beta	(In) A scalar constant used to scale OutVec.
OutVec	(In) The vector where the calculation result is stored or whether it is a single vector or multi-vector.
NumCalls	(In) The number of times the operation is called or the tuning level wanted.
List	(In) Used for denoting the use of symbolic vectors for both InVec and OutVec, as well as for level of aggressive tuning if either NumCalls not known or to be overridden. Options are shown below. It should be noted that by using these options the associated vector or NumCalls becomes invalid.

Returns:: Stores the workload hint in the matrix if the operation is valid. If the operation is not valid an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix.

These replace InVec.

bool symminvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symminmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace OutVec.

bool symmoutvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmoutmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

bool tune: If true, have OSKI tune moderately rather than using the number of calls passed in.
bool tuneaggressive: If true, have OSKI tune aggressively rather than using the number of calls passed in.

int Epetra_OskiMatrix::SetHintMultiplyAndMatTransMultiply	(	bool	TransA,
		double	Alpha,
		const Epetra_OskiMultiVector &	InVec,
		double	Beta,
		const Epetra_OskiMultiVector &	OutVec,
		double	Omega,
		const Epetra_OskiMultiVector &	InVec2,
		double	Zeta,
		const Epetra_OskiMultiVector &	OutVec2,
		int	NumCalls,
		const Teuchos::ParameterList &	List
	)

Workload hints for computing two matrix-vector multiplies used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.

In parallel the routine uses symbolic vectors. This is done for two reasons. Doing this saves on data allocation and potentially communication overhead. For a matrix-vector routine there should be no advantage to having the actual vector, as its size must be the same as a matrix dimension. For a matrix-multivector routine there could be gains from knowing the number of vectors in the multi-vector. However, OSKI does not perform multi-vector optimizations, so there is no need to add the overhead.

Parameters:

Trans	(In) If Trans = true then the transpose of the matrix will be used in computing the product.
Alpha	(In) A scalar constant used to scale InVec.
InVec	(In) The vector the matrix is multiplied by or whether it is a single vector or multi-vector.
Beta	(In) A scalar constant used to scale OutVec.
OutVec	(In) The vector where the calculation result is stored or whether it is a single vector or multi-vector.
Omega	(In) A scalar constant used to scale InVec2.
InVec2	(In) The vector the matrix is multiplied by or whether it is a single vector or multi-vector.
Zeta	(In) A scalar constant used to scale OutVec2.
OutVec2	(In) The vector where the calculation result is stored or whether it is a single vector or multi-vector.
NumCalls	(In) The number of times the operation is called or the tuning level wanted.
List	(In) Used for denoting the use of symbolic vectors for both InVec and OutVec, as well as for level of aggressive tuning if either NumCalls not known or to be overridden. Options are shown below. It should be noted that by using these options the associated vector or NumCalls becomes invalid.

Returns:: Stores the workload hint in the matrix if the operation is valid. If the operation is not valid an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix.

These replace InVec.

bool symminvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symminmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace OutVec.

bool symmoutvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmoutmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace InVec2.

bool symminvec2: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symminmultivec2: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace OutVec2.

bool symmoutvec2: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmoutmultivec2: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

bool tune: If true, have OSKI tune moderately rather than using the number of calls passed in.
bool tuneaggressive: If true, have OSKI tune aggressively rather than using the number of calls passed in.

int Epetra_OskiMatrix::SetHintPowMultiply	(	bool	TransA,
		double	Alpha,
		const Epetra_OskiMultiVector &	InVec,
		double	Beta,
		const Epetra_OskiMultiVector &	OutVec,
		const Epetra_OskiMultiVector &	Intermediate,
		int	Power,
		int	NumCalls,
		const Teuchos::ParameterList &	List
	)

Workload hints for computing a matrix-vector multiply performed Power times used by OskiTuneMat to optimize the data structure storage and the routine to compute the calculation.

In parallel the routine uses symbolic vectors. This is done for two reasons. Doing this saves on data allocation and potentially communication overhead. For a matrix-vector routine there should be no advantage to having the actual vector, as its size must be the same as a matrix dimension. For a matrix-multivector routine there could be gains from knowing the number of vectors in the multi-vector. However, OSKI does not perform multi-vector optimizations, so there is no need to add the overhead.

Parameters:

Trans	(In) If Trans = true then the transpose of the matrix will be used in computing the product.
Alpha	(In) A scalar constant used to scale InVec.
InVec	(In) The vector the matrix is multiplied by or whether it is a single vector or multi-vector.
Beta	(In) A scalar constant used to scale OutVec.
OutVec	(In) The vector where the calculation result is stored or whether it is a single vector or multi-vector.
Intermediate	(In) The multi-vector where result of the first product can be stored or whether it is a single vector or multi-vector. If this quantity is NULL then the intermediate product is not stored.
Power	(In) The power to raise the matrix to in the calculation.
NumCalls	(In) The number of times the operation is called or the tuning level wanted.
List	(In) Used for denoting the use of symbolic vectors for both InVec and OutVec, as well as for level of aggressive tuning if either NumCalls not known or to be overridden. Options are shown below. It should be noted that by using these options the associated vector or NumCalls becomes invalid.

Returns:: Stores the workload hint in the matrix if the operation is valid. If the operation is not valid an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix.

These replace InVec.

bool symminvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symminmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

These replace OutVec.

bool symmoutvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmoutmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

This replaces Intermediate.

bool symmintermultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

bool tune: If true, have OSKI tune moderately rather than using the number of calls passed in.
bool tuneaggressive: If true, have OSKI tune aggressively rather than using the number of calls passed in.

int Epetra_OskiMatrix::SetHintSolve	(	bool	TransA,
		double	Alpha,
		const Epetra_OskiMultiVector &	Vector,
		int	NumCalls,
		const Teuchos::ParameterList &	List
	)

Workload hints for computing a triangular solve used by OskiTuneMat to optimize the data structure storage, and the routine to compute the calculation.

In parallel the routine uses symbolic vectors. This is done for two reasons. Doing this saves on data allocation and potentially communication overhead. For a matrix-vector routine there should be no advantage to having the actual vector, as its size must be the same as a matrix dimension. For a matrix-multivector routine there could be gains from knowing the number of vectors in the multi-vector. However, OSKI does not perform multi-vector optimizations, so there is no need to add the overhead.

Parameters:

Trans	(In) If Trans = true then the transpose of the matrix will be used in computing the product.
Alpha	(In) A scalar constant used to scale InVec.
Vector	(In) The vector being used in the solve and to store the solution.
NumCalls	(In) The number of times the operation is called or the tuning level wanted.
List	(In) Used for denoting the use of a symbolic vectors, as well as for level of aggressive tuning if either NumCalls not known or to be overridden. Options are shown below. It should be noted that by using these options the associated vector or NumCalls becomes invalid.

Returns:: Stores the workload hint in the matrix if the operation is valid. If the operation is not valid an error code is returned.

Options that can be passed to the List are presented below. They are: "<type> <option name>: <description of purpose>". The available hints are grouped by section, and only one hint from each section can be true for a given matrix.

These replace Vector.

bool symmvec: If true, use a symbolic vector rather than the vector passed in for tuning purposes.
bool symmmultivec: If true, use a symbolic multi-vector rather than the multi-vector passed in for tuning purposes.

bool tune: If true, have OSKI tune moderately rather than using the number of calls passed in.
bool tuneaggressive: If true, have OSKI tune aggressively rather than using the number of calls passed in.

int Epetra_OskiMatrix::Solve	(	bool	TransA,
		const Epetra_MultiVector &	X,
		Epetra_MultiVector &	Y,
		double	Alpha = `1.0`
	)		const

Performs a triangular solve of Y = Alpha*(this^TransA)^-1*X where this is a triangular matrix.

The vector X can be either be an Epetra_MultiVector or Epetra_OskiMultiVector.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in solving the equations.
X	(In) The multi-vector solved against.
Y	(Out) The solution multi-vector.
Alpha	(In) A scalar constant used to scale X.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::Solve	(	bool	Upper,
		bool	TransA,
		bool	UnitDiagonal,
		const Epetra_Vector &	x,
		Epetra_Vector &	y
	)		const

Performs a triangular solve of y = (this^TransA)^-1*x where this is a triangular matrix.

The vector x can be either be an Epetra_Vector or Epetra_OskiVector. The OskiMatrix must already be triangular, and the UnitDiagonal setting associated with it will be used.

Parameters:

Upper	(In) This parameter is ignored, and is here only to match the Epetra_CrsMatrix::Solve syntax.
TransA	(In) If TransA = TRUE then use the transpose of the matrix in solving the equations.
UnitDiagonal	(In) This parameter is ignored only here to match the Epetra_CrsMatrix::Solve syntax.
x	(In) The vector solved against.
y	(Out) The solution vector.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

Reimplemented from Epetra_CrsMatrix.

int Epetra_OskiMatrix::Solve	(	bool	Upper,
		bool	TransA,
		bool	UnitDiagonal,
		const Epetra_MultiVector &	X,
		Epetra_MultiVector &	Y
	)		const `[virtual]`

Performs a triangular solve of Y = (this^TransA)^-1*X where this is a triangular matrix.

The vector X can be either be an Epetra_MultiVector or Epetra_OskiMultiVector. The OskiMatrix must already be triangular, and the UnitDiagonal setting associated with it will be used.

Parameters:

Upper	(In) This parameter is ignored only here to match the Epetra_CrsMatrix::Solve syntax.
TransA	(In) If TransA = TRUE then use the transpose of the matrix in solving the equations.
UnitDiagonal	(In) This parameter is ignored only here to match the Epetra_CrsMatrix::Solve syntax.
X	(In) The multi-vector solved against.
Y	(Out) The solution multi-vector.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

Reimplemented from Epetra_CrsMatrix.

int Epetra_OskiMatrix::Solve	(	bool	TransA,
		const Epetra_Vector &	x,
		Epetra_Vector &	y,
		double	Alpha = `1.0`
	)		const

Performs a triangular solve of y = Alpha*(this^TransA)^-1*x where this is a triangular matrix.

The vector x can be either be an Epetra_Vector or Epetra_OskiVector.

Parameters:

TransA	(In) If TransA = TRUE then use the transpose of the matrix in solving the equations.
x	(In) The vector solved against.
y	(Out) The solution vector.
Alpha	(In) A scalar constant used to scale x.

Returns:: Integer error code, set to 0 if successful.

Precondition:: Filled()==true

Postcondition:: Unchanged

int Epetra_OskiMatrix::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. WARNING: this could be expensive.

The reason this function could be expensive is its underlying implementation. Both the OSKI and Epetra versions of the Matrix must be changed when the matrix has been permuted. When this is the case, a call must be made to the Epetra SumIntoMyValues, and NumEntries calls must be made to a function that changes the OSKI matrix's values one at a time.

Parameters:

MyRow	- (In) Row number (in local coordinates) to put elements.
NumEntries	- (In) Number of entries.
Values	- (In) Values to enter.
Indices	- (In) Local column indices corresponding to values.

Returns:: Integer error code, set to 0 if successful. Note that if the allocated length of the row has to be expanded, a positive warning code may be returned. This should be treated as a fatal error, as part of the data will be changed, and OSKI cannot support adding in new data values.

Precondition:: IndicesAreLocal()==true

Postcondition:: The given Values at the given Indices have been summed into the entries of MyRow.

int Epetra_OskiMatrix::TuneMatrix ( )

Tunes the matrix multiply if its deemed profitable.

The routine tunes based upon user provided hints if given. If hints are not given the tuning is performed based on expected future workload for the calculation.

Returns:: On success returns a non-negative status code of the transformations performed. On failure an error code is returned.

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

Epetra_OskiMatrix.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation