Ifpack_SerialTriDiMatrix Class Reference

Ifpack_SerialTriDiMatrix: A class for constructing and using real double precision general TriDi matrices. More...

#include <Ifpack_SerialTriDiMatrix.h>

Inheritance diagram for Ifpack_SerialTriDiMatrix:

Collaboration diagram for Ifpack_SerialTriDiMatrix:

Public Member Functions
Constructor/Destructor Methods
	Ifpack_SerialTriDiMatrix (bool set_object_label=true)
	Default constructor; defines a zero size object. More...
	Ifpack_SerialTriDiMatrix (int NumRowCol, bool set_object_label=true)
	Shaped constructor; defines a variable-sized object. More...
	Ifpack_SerialTriDiMatrix (Epetra_DataAccess CV, double *A_in, int NumRowCol, bool set_object_label=true)
	Set object values from two-dimensional array. More...
	Ifpack_SerialTriDiMatrix (const Ifpack_SerialTriDiMatrix &Source)
	Ifpack_SerialTriDiMatrix copy constructor.
virtual	~Ifpack_SerialTriDiMatrix ()
	Ifpack_SerialTriDiMatrix destructor.
Shaping/sizing Methods
int	Shape (int NumRowCol)
	Set dimensions of a Ifpack_SerialTriDiMatrix object; init values to zero. More...
int	Reshape (int, int)
Mathematical methods
int	Multiply (char TransA, char TransB, double ScalarAB, const Ifpack_SerialTriDiMatrix &A, const Ifpack_SerialTriDiMatrix &B, double ScalarThis)
	Matrix-Matrix multiplication, this = ScalarThis*this + ScalarAB*A*B. More...
int	Scale (double ScalarA)
	Matrix-Vector multiplication, y = A*x, where 'this' == A. More...
virtual double	NormOne () const
	Computes the 1-Norm of the this matrix. More...
virtual double	NormInf () const
	Computes the Infinity-Norm of the this matrix.
Data Accessor methods
Ifpack_SerialTriDiMatrix &	operator= (const Ifpack_SerialTriDiMatrix &Source)
	Value copy from one matrix to another. More...
bool	operator== (const Ifpack_SerialTriDiMatrix &rhs) const
	Comparison operator. More...
bool	operator!= (const Ifpack_SerialTriDiMatrix &rhs) const
	Inequality operator. More...
Ifpack_SerialTriDiMatrix &	operator+= (const Ifpack_SerialTriDiMatrix &Source)
	Add one matrix to another. More...
double &	operator() (int RowIndex, int ColIndex)
	Element access function. More...
const double &	operator() (int RowIndex, int ColIndex) const
	Element access function. More...
int	Random ()
	Column access function. More...
int	N () const
	Returns column dimension of system.
int	LDA () const
double *	A () const
	Returns pointer to the this matrix.
double *	DL ()
	Returns pointer to the this matrix.
double *	DL () const
double *	D ()
double *	D () const
double *	DU ()
double *	DU () const
double *	DU2 ()
double *	DU2 () const
Epetra_DataAccess	CV () const
	Returns the data access mode of the this matrix.
I/O methods
virtual void	Print (std::ostream &os) const
	Print service methods; defines behavior of ostream << operator.
Deprecated methods (will be removed in later versions of this class)
virtual double	OneNorm () const
	Computes the 1-Norm of the this matrix (identical to NormOne() method). More...
virtual double	InfNorm () const
	Computes the Infinity-Norm of the this matrix (identical to NormInf() method).
Additional methods to support Ifpack_SerialTriDiOperator interface
virtual int	SetUseTranspose (bool UseTranspose_in)
	If set true, transpose of this operator will be applied. More...
virtual int	ApplyInverse (const Ifpack_SerialTriDiMatrix &X, Ifpack_SerialTriDiMatrix &Y)
	Returns the result of a Ifpack_SerialTriDiOperator inverse applied to an Ifpack_SerialTriDiMatrix X in Y. More...
virtual const char *	Label () const
	Returns a character string describing the operator.
virtual bool	UseTranspose () const
	Returns the current UseTranspose setting.
virtual bool	HasNormInf () const
	Returns true if the this object can provide an approximate Inf-norm, false otherwise.
virtual int	RowColDim () const
	Returns the column dimension of operator.
Public Member Functions inherited from Epetra_BLAS
	Epetra_BLAS (const Epetra_BLAS &BLAS)
float	ASUM (const int N, const float *X, const int INCX=1) const
double	ASUM (const int N, const double *X, const int INCX=1) const
float	DOT (const int N, const float *X, const float *Y, const int INCX=1, const int INCY=1) const
double	DOT (const int N, const double *X, const double *Y, const int INCX=1, const int INCY=1) const
float	NRM2 (const int N, const float *X, const int INCX=1) const
double	NRM2 (const int N, const double *X, const int INCX=1) const
void	SCAL (const int N, const float ALPHA, float *X, const int INCX=1) const
void	SCAL (const int N, const double ALPHA, double *X, const int INCX=1) const
void	COPY (const int N, const float *X, float *Y, const int INCX=1, const int INCY=1) const
void	COPY (const int N, const double *X, double *Y, const int INCX=1, const int INCY=1) const
int	IAMAX (const int N, const float *X, const int INCX=1) const
int	IAMAX (const int N, const double *X, const int INCX=1) const
void	AXPY (const int N, const float ALPHA, const float *X, float *Y, const int INCX=1, const int INCY=1) const
void	AXPY (const int N, const double ALPHA, const double *X, double *Y, const int INCX=1, const int INCY=1) const
void	GEMV (const char TRANS, const int M, const int N, const float ALPHA, const float *A, const int LDA, const float *X, const float BETA, float *Y, const int INCX=1, const int INCY=1) const
void	GEMV (const char TRANS, const int M, const int N, const double ALPHA, const double *A, const int LDA, const double *X, const double BETA, double *Y, const int INCX=1, const int INCY=1) const
void	GEMM (const char TRANSA, const char TRANSB, const int M, const int N, const int K, const float ALPHA, const float *A, const int LDA, const float *B, const int LDB, const float BETA, float *C, const int LDC) const
void	GEMM (const char TRANSA, const char TRANSB, const int M, const int N, const int K, const double ALPHA, const double *A, const int LDA, const double *B, const int LDB, const double BETA, double *C, const int LDC) const
void	SYMM (const char SIDE, const char UPLO, const int M, const int N, const float ALPHA, const float *A, const int LDA, const float *B, const int LDB, const float BETA, float *C, const int LDC) const
void	SYMM (const char SIDE, const char UPLO, const int M, const int N, const double ALPHA, const double *A, const int LDA, const double *B, const int LDB, const double BETA, double *C, const int LDC) const
void	TRMM (const char SIDE, const char UPLO, const char TRANSA, const char DIAG, const int M, const int N, const float ALPHA, const float *A, const int LDA, float *B, const int LDB) const
void	TRMM (const char SIDE, const char UPLO, const char TRANSA, const char DIAG, const int M, const int N, const double ALPHA, const double *A, const int LDA, double *B, const int LDB) const
void	SYRK (const char UPLO, const char TRANS, const int N, const int K, const float ALPHA, const float *A, const int LDA, const float BETA, float *C, const int LDC) const
void	SYRK (const char UPLO, const char TRANS, const int N, const int K, const double ALPHA, const double *A, const int LDA, const double BETA, double *C, const int LDC) const

Protected Member Functions
void	CopyMat (const double *Source, int NumRowCol, double *Target, int NRC2, bool add=false)
void	CleanupData ()

Protected Attributes
int	N_
int	LDA_
bool	A_Copied_
Epetra_DataAccess	CV_
double *	A_
double *	DL_
double *	D_
double *	DU_
double *	DU2_
bool	UseTranspose_

Friends
class	Epetra_VbrMatrix

Detailed Description

Ifpack_SerialTriDiMatrix: A class for constructing and using real double precision general TriDi matrices.

The Ifpack_SerialTriDiMatrix class enables the construction and use of real-valued, general,
double-precision TriDi matrices.  It is built on the BLAS, and derives from the Epetra_BLAS.

The Ifpack_SerialTriDiMatrix class is intended to provide very basic support for TriDiagonal matrices.

Constructing Ifpack_SerialTriDiMatrix Objects

There are four Ifpack_SerialTriDiMatrix constructors. The first constructs a zero-sized object which should be made to appropriate length using the Shape() or Reshape() functions and then filled with the [] or () operators. The second constructs an object sized to the dimensions specified, which should be filled with the [] or () operators. The third is a constructor that accepts user data as a 2D array, and the fourth is a copy constructor. The third constructor has two data access modes (specified by the Epetra_DataAccess argument):

1. Copy mode - Allocates memory and makes a copy of the user-provided data. In this case, the user data is not needed after construction.
2. View mode - Creates a "view" of the user data. In this case, the user data is required to remain intact for the life of the object.

Warning

View mode is extremely dangerous from a data hiding perspective. Therefore, we strongly encourage users to develop code using Copy mode first and only use the View mode in a secondary optimization phase.

Extracting Data from Ifpack_SerialTriDiMatrix Objects

Once a Ifpack_SerialTriDiMatrix is constructed, it is possible to view the data via access functions.

Warning

Use of these access functions cam be extremely dangerous from a data hiding perspective.

Vector and Utility Functions

Once a Ifpack_SerialTriDiMatrix is constructed, several mathematical functions can be applied to the object. Specifically:

• Multiplication.
• Norms.

Counting floating point operations The Ifpack_SerialTriDiMatrix class has Epetra_CompObject as a base class. Thus, floating point operations are counted and accumulated in the Epetra_Flop object (if any) that was set using the SetFlopCounter() method in the Epetra_CompObject base class.

Definition at line 112 of file Ifpack_SerialTriDiMatrix.h.

Constructor & Destructor Documentation

Ifpack_SerialTriDiMatrix::Ifpack_SerialTriDiMatrix

(

bool

set_object_label = true

)

Default constructor; defines a zero size object.

Ifpack_SerialTriDiMatrix objects defined by the default constructor should be sized with the Shape() or Reshape functions. Values should be defined by using the () operators.

Definition at line 47 of file Ifpack_SerialTriDiMatrix.cpp.

References Copy.

Ifpack_SerialTriDiMatrix::Ifpack_SerialTriDiMatrix	(	int	NumRowCol,
		bool	set_object_label = true
	)

Shaped constructor; defines a variable-sized object.

Parameters

In	NumRowCol - Number of rows and columns in object.

Ifpack_SerialTriDiMatrix objects defined by the shaped constructor are already shaped to the dimensions given as a parameters. All values are initialized to 0. Calling this constructor is equivalent to using the default constructor, and then calling the Shape function on it. Values should be defined by using the [] or () operators.

Definition at line 62 of file Ifpack_SerialTriDiMatrix.cpp.

References Copy, and Shape().

Ifpack_SerialTriDiMatrix::Ifpack_SerialTriDiMatrix	(	Epetra_DataAccess	CV,
		double *	A_in,
		int	NumRowCol,
		bool	set_object_label = true
	)

Set object values from two-dimensional array.

Parameters

In	Epetra_DataAccess - Enumerated type set to Copy or View.
In	A - Pointer to an array of double precision numbers. The
In	NumRows - Number of rows and columns in object.

See Detailed Description section for further discussion.

Definition at line 84 of file Ifpack_SerialTriDiMatrix.cpp.

References Copy.

Member Function Documentation

virtual int Ifpack_SerialTriDiMatrix::ApplyInverse ( const Ifpack_SerialTriDiMatrix &  X, Ifpack_SerialTriDiMatrix &  Y  )

inlinevirtual

Returns the result of a Ifpack_SerialTriDiOperator inverse applied to an Ifpack_SerialTriDiMatrix X in Y.

Parameters

In	X - A Ifpack_SerialTriDiMatrix to solve for.
Out	Y -A Ifpack_SerialTriDiMatrix containing result.

Returns

Integer error code, set to 0 if successful.

Definition at line 417 of file Ifpack_SerialTriDiMatrix.h.

int Ifpack_SerialTriDiMatrix::Multiply	(	char	TransA,
		char	TransB,
		double	ScalarAB,
		const Ifpack_SerialTriDiMatrix &	A,
		const Ifpack_SerialTriDiMatrix &	B,
		double	ScalarThis
	)

Matrix-Matrix multiplication, this = ScalarThis*this + ScalarAB*A*B.

This function performs a variety of matrix-matrix multiply operations.

Parameters

In	TransA - Operate with the transpose of A if = 'T', else no transpose if = 'N'.
In	TransB - Operate with the transpose of B if = 'T', else no transpose if = 'N'.
In	ScalarAB - Scalar to multiply with A*B.
In	A - TriDi Matrix.
In	B - TriDi Matrix.
In	ScalarThis - Scalar to multiply with this.

Returns

Integer error code, set to 0 if successful.

Definition at line 380 of file Ifpack_SerialTriDiMatrix.cpp.

double Ifpack_SerialTriDiMatrix::NormOne ( ) const

virtual

Computes the 1-Norm of the this matrix.

Returns

Integer error code, set to 0 if successful.

Definition at line 344 of file Ifpack_SerialTriDiMatrix.cpp.

Referenced by NormInf(), and OneNorm().

virtual double Ifpack_SerialTriDiMatrix::OneNorm ( ) const

inlinevirtual

Computes the 1-Norm of the this matrix (identical to NormOne() method).

Returns

Integer error code, set to 0 if successful.

Definition at line 386 of file Ifpack_SerialTriDiMatrix.h.

References NormOne().

Referenced by Ifpack_SerialTriDiSolver::Factor(), and Ifpack_SerialTriDiSolver::ReciprocalConditionEstimate().

bool Ifpack_SerialTriDiMatrix::operator!= ( const Ifpack_SerialTriDiMatrix &  rhs ) const

inline

Inequality operator.

operator!= simply returns the negation of operator==.

Definition at line 278 of file Ifpack_SerialTriDiMatrix.h.

double & Ifpack_SerialTriDiMatrix::operator() ( int  RowIndex, int  ColIndex  )

inline

Element access function.

The parentheses operator returns the element in the ith row and jth column if A(i,j) is specified,

Returns

Element from the specified row and column.

        \warning No bounds checking is done unless Epetra is compiled with HAVE_EPETRA_ARRAY_BOUNDS_CHECK.

Definition at line 466 of file Ifpack_SerialTriDiMatrix.h.

const double & Ifpack_SerialTriDiMatrix::operator() ( int  RowIndex, int  ColIndex  ) const

inline

Element access function.

The parentheses operator returns the element in the ith row and jth column if A(i,j) is specified, the expression A[j][i] (note that i and j are reversed) will return the same element. Thus, A(i,j) = A[j][i] for all valid i and j.

Returns

Element from the specified row and column.

        \warning No bounds checking is done unless Epetra is compiled with HAVE_EPETRA_ARRAY_BOUNDS_CHECK.

Definition at line 502 of file Ifpack_SerialTriDiMatrix.h.

Ifpack_SerialTriDiMatrix & Ifpack_SerialTriDiMatrix::operator+=

(

const Ifpack_SerialTriDiMatrix &

Source

)

Add one matrix to another.

The operator+= allows one to add the values from one existin SerialTriDiMatrix to another, as long as there is enough room in the target to hold the source.

Returns

Values of the left hand side matrix are modified by the addition of the values of the right hand side matrix.

Definition at line 304 of file Ifpack_SerialTriDiMatrix.cpp.

References A(), and N().

Ifpack_SerialTriDiMatrix & Ifpack_SerialTriDiMatrix::operator=

(

const Ifpack_SerialTriDiMatrix &

Source

)

Value copy from one matrix to another.

The operator= allows one to copy the values from one existing SerialTriDiMatrix to another, as long as there is enough room in the target to hold the source.

Returns

Values of the left hand side matrix are modified by the values of the right hand side matrix.

Definition at line 218 of file Ifpack_SerialTriDiMatrix.cpp.

References Copy, Label(), N(), and View.

bool Ifpack_SerialTriDiMatrix::operator==

(

const Ifpack_SerialTriDiMatrix &

rhs

)

const

Comparison operator.

operator== compares two Ifpack_SerialTriDiMatrix objects, returns false if sizes are different, or if any coefficients differ by an amount greater than Epetra_MinDouble.

Definition at line 285 of file Ifpack_SerialTriDiMatrix.cpp.

int Ifpack_SerialTriDiMatrix::Random

(

)

Column access function.

The parentheses operator returns the element in the ith row and jth column if A(i,j) is specified, the expression A[j][i] (note that i and j are reversed) will return the same element. Thus, A(i,j) = A[j][i] for all valid i and j.

Returns

Pointer to address of specified column.

Warning

No bounds checking can be done for the index i in the expression A[j][i].

No bounds checking is done unless Epetra is compiled with HAVE_EPETRA_ARRAY_BOUNDS_CHECK.Column access function.

The parentheses operator returns the element in the ith row and jth column if A(i,j) is specified, the expression A[j][i] (note that i and j are reversed) will return the same element. Thus, A(i,j) = A[j][i] for all valid i and j.

Returns

Pointer to address of specified column.

Warning

No bounds checking can be done for the index i in the expression A[j][i].

No bounds checking is done unless Epetra is compiled with HAVE_EPETRA_ARRAY_BOUNDS_CHECK.Set matrix values to random numbers.

SerialTriDiMatrix uses the random number generator provided by Epetra_Util. The matrix values will be set to random values on the interval (-1.0, 1.0).

Returns

Integer error code, set to 0 if successful.

Definition at line 390 of file Ifpack_SerialTriDiMatrix.cpp.

References Epetra_Util::RandomDouble().

int Ifpack_SerialTriDiMatrix::Scale

(

double

ScalarA

)

Matrix-Vector multiplication, y = A*x, where 'this' == A.

Matrix-Matrix multiplication with a symmetric matrix A.

  If SideA = 'L', compute \e this = ScalarThis*\e this + ScalarAB*A*B.
  If SideA = 'R', compute \e this = ScalarThis*\e this + ScalarAB*B*A.

This function performs a variety of matrix-matrix multiply operations.

Parameters

In	SideA - Specifies order of A relative to B.
In	ScalarAB - Scalar to multiply with A*B.
In	A - Symmetric TriDi Matrix, either upper or lower triangle will be used depending on value of A.Upper().
In	B - TriDi Matrix.
In	ScalarThis - Scalar to multiply with this.

Returns

Integer error code, set to 0 if successful.

Parameters

ScalarA

(In) Scalar to multiply with A.

Returns

Integer error code, set to 0 if successful.

Definition at line 364 of file Ifpack_SerialTriDiMatrix.cpp.

virtual int Ifpack_SerialTriDiMatrix::SetUseTranspose ( bool  UseTranspose_in )

inlinevirtual

If set true, transpose of this operator will be applied.

This flag allows the transpose of the given operator to be used implicitly.  Setting this flag
affects only the Apply() and ApplyInverse() methods.  If the implementation of this interface
does not support transpose use, this method should return a value of -1.

Parameters

In	UseTranspose -If true, multiply by the transpose of operator, otherwise just use operator.

Returns

Integer error code, set to 0 if successful. Set to -1 if this implementation does not support transpose.

Definition at line 405 of file Ifpack_SerialTriDiMatrix.h.

int Ifpack_SerialTriDiMatrix::Shape

(

int

NumRowCol

)

Set dimensions of a Ifpack_SerialTriDiMatrix object; init values to zero.

Parameters

In	NumRowCol - Number of rows and columns in object.

Allows user to define the dimensions of a Ifpack_SerialTriDiMatrix at any point. This function can be called at any point after construction. Any values that were previously in this object are destroyed and the resized matrix starts off with all zero values.

Returns

Integer error code, set to 0 if successful.

Definition at line 179 of file Ifpack_SerialTriDiMatrix.cpp.

Referenced by Ifpack_SerialTriDiMatrix(), and Ifpack_TriDiContainer::Initialize().

---

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

• Ifpack_SerialTriDiMatrix.h
• Ifpack_SerialTriDiMatrix.cpp