Epetra_OskiMatrix Class Reference

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:

Inheritance graph
[legend]
List of all members.

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 = Alpha*this^TransA*x + 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 = Alpha*this^TransA*X + 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)^-1*x 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)^-1*X 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 = Alpha*this^TransA*this*x + Beta*y or y = Alpha*this*this^TransA*x + Beta*y.
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 = Alpha*this^TransA*this*X + Beta*Y or Y = Alpha*this*this^TransA*X + Beta*Y.
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 = Alpha*this*x + Beta*y and z = Omega*this^TransA*w + Zeta*z.
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 = Alpha*this*X + Beta*Y and Z = Omega*this^TransA*W + Zeta*Z.
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)^Power*x + 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)^Power*x + 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_OskiMatrixViewTransformedMat () 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_OskiPermutationViewRowPermutation () const
 Returns a read only row/left permutation of the Matrix.
const Epetra_OskiPermutationViewColumnPermutation () 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.

Private Attributes

const Epetra_CrsMatrixEpetra_View_
oski_matrix_t A_tunable_
bool Copy_Created_

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:

Definition at line 82 of file Epetra_OskiMatrix.h.


Constructor & Destructor Documentation

Epetra_OskiMatrix::Epetra_OskiMatrix ( const Epetra_OskiMatrix Source  ) 

Copy constructor.

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>"

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

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

virtual Epetra_OskiMatrix::~Epetra_OskiMatrix (  )  [virtual]

Destructor.


Member Function Documentation

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.

Reimplemented from Epetra_CrsMatrix.

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.

Reimplemented from Epetra_CrsMatrix.

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.

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::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::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::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  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::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_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::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^T*this*x otherwise compute this*this^T*x.
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 this*x is stored if TransA = true and this^T*x 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^T*this*X otherwise compute this*this^T*X.
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 this*X is stored if TransA = true and this^T*X 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::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::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::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 this*x ... 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::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.

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::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.

These replace OutVec.

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.

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^T*this*x will be computed otherwise this*this^T*x 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.

These replace OutVec.

These replace Intermediate.

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.

These replace OutVec.

These replace InVec2.

These replace OutVec2.

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.

These replace OutVec.

This replaces Intermediate.

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.

int Epetra_OskiMatrix::IsMatrixTransformed (  )  const

Returns 1 if the matrix has been reordered by tuning, and 0 if it has not been.

const Epetra_OskiMatrix& 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& Epetra_OskiMatrix::ViewRowPermutation (  )  const

Returns a read only row/left permutation of the Matrix.

const Epetra_OskiPermutation& Epetra_OskiMatrix::ViewColumnPermutation (  )  const

Returns a read only column/right permutation of the Matrix.

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::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.


Member Data Documentation

const Epetra_CrsMatrix* Epetra_OskiMatrix::Epetra_View_ [private]

Definition at line 785 of file Epetra_OskiMatrix.h.

oski_matrix_t Epetra_OskiMatrix::A_tunable_ [private]

Definition at line 786 of file Epetra_OskiMatrix.h.

bool Epetra_OskiMatrix::Copy_Created_ [private]

Definition at line 787 of file Epetra_OskiMatrix.h.


The documentation for this class was generated from the following file:
Generated on Wed May 12 21:41:09 2010 for Epetra Package Browser (Single Doxygen Collection) by  doxygen 1.4.7