Amesos_Mumps Class Reference

Amesos_Mumps: An object-oriented wrapper for CERFACS' MUMPS. More...

#include <Amesos_Mumps.h>

Inheritance diagram for Amesos_Mumps:

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

Public Member Functions
bool	MatrixShapeOK () const
	Returns true if the solver can handle this matrix shape.
const Epetra_Comm &	Comm () const
	Returns a pointer to the Epetra_Comm communicator associated with this matrix.
const Epetra_LinearProblem *	GetProblem () const
	Gets a pointer to the Epetra_LinearProblem.
Constructor methods
	Amesos_Mumps (const Epetra_LinearProblem &LinearProblem)
	Amesos_Mumps Constructor.
	~Amesos_Mumps (void)
	Amesos_Mumps Destructor.
Mathematical functions.
int	SymbolicFactorization ()
	Performs SymbolicFactorization on the matrix A.
int	NumericFactorization ()
	Performs NumericFactorization on the matrix A.
int	Solve ()
	Solves A X = B (or AT x = B).
void	Destroy ()
	Destroys all data associated with this object.
int	SetUseTranspose (bool UseTranspose)
	If set true, X will be set to the solution of AT X = B (not A X = B).
bool	UseTranspose () const
	Returns the current UseTranspose setting.
int	SetParameters (Teuchos::ParameterList &ParameterList)
	Updates internal variables.
Print functions
void	PrintTiming ()
	Prints timing information.
void	PrintStatus ()
	Prints information about the factorization and solution phases.
MUMPS' specify functions
int	ComputeSchurComplement (bool flag, int NumSchurComplementRows, int *SchurComplementRows)
	Returns the Schur complement matrix as an Epetra_CrsMatrix.
Epetra_CrsMatrix *	GetCrsSchurComplement ()
	Returns the Schur complement in an Epetra_CrsMatrix on host only.
Epetra_SerialDenseMatrix *	GetDenseSchurComplement ()
	Returns the Schur complement as a SerialDenseMatrix (on host only).
int	SetPrecscaling (double *ColSca, double *RowSca)
	Set prescaling.
int	SetRowScaling (double *RowSca)
	Set row scaling.
int	SetColScaling (double *ColSca)
	Set column scaling.
int	SetOrdering (int *PermIn)
	Sets ordering.
int	SetMaxis (int Maxis)
	Sets the Maxis value (see MUMPS' manual).
int	SetMaxs (int Maxs)
	Sets the Maxs value (see MUMPS' manual).
double *	GetRINFO ()
	Gets the pointer to the RINFO array (defined on all processes).
int *	GetINFO ()
	Gets the pointer to the INFO array (defined on all processes).
double *	GetRINFOG ()
	Gets the pointer to the RINFOG array (defined on host only).
int *	GetINFOG ()
	Get the pointer to the INFOG array (defined on host only).
int	SetICNTL (int *ictnl)
	Copies the input array (of size 40) into the internally stored ICNTL array.
int	SetICNTL (int pos, int value)
	Set ICNTL[pos] to value. pos is expressed in FORTRAN style (starting from 1).
int	SetCNTL (double *ctnl)
	Copy the input array (of size 5) into the internally stored CNTL array.
int	SetCNTL (int pos, double value)
	Set CNTL[pos] to value. pos is expressed in FORTRAN style (starting from 1).
Protected Member Functions
Epetra_RowMatrix &	Matrix ()
	Returns a reference to the linear system matrix.
Epetra_Map &	RedistrMap ()
	Returns a reference to the map for redistributed matrix.
Epetra_Import &	RedistrImporter ()
	Returns a reference for the redistributed importer.
Epetra_RowMatrix &	RedistrMatrix (const bool ImportMatrix=false)
	Returns a reference to the redistributed matrix, imports it is ImportMatrix is true.
Epetra_Map &	SerialMap ()
	Returns a reference to the map with all elements on process 0.
Epetra_Import &	SerialImporter ()
	Returns a reference to the importer for SerialMap().
int	ConvertToTriplet (const bool OnlyValues)
	Converts to MUMPS format (COO format).
void	CheckError ()
	Checks for MUMPS error, prints them if any. See MUMPS' manual.
void	CheckParameters ()
	Check input parameters.
void	SetICNTLandCNTL ()
Protected Attributes
bool	IsConvertToTripletOK_
	true if matrix has already been converted to COO format
bool	IsComputeSchurComplementOK_
	true if the Schur complement has been computed (need to free memory)
bool	NoDestroy_
DMUMPS_STRUC_C	MDS
	Mumps data structure for double-precision.
vector< int >	Row
	row indices of nonzero elements
vector< int >	Col
	column indices of nonzero elements
vector< double >	Val
	values of nonzero elements
int	MaxProcs_
	Maximum number of processors in the MUMPS' communicator.
bool	UseTranspose_
	If true, solve the problem with AT.
double	Threshold_
	Discard all elements whose absolute value is below this value.
int	icntl_ [40]
double	cntl_ [5]
double *	RowSca_
	Row and column scaling.
double *	ColSca_
	Row and column scaling.
int *	PermIn_
	PermIn for MUMPS.
int	Maxis_
	MAXIS for MUMPS.
int	Maxs_
int	NumSchurComplementRows_
	Number of rows in the Schur complement (if required).
int *	SchurComplementRows_
	Rows for the Schur complement (if required).
Epetra_CrsMatrix *	CrsSchurComplement_
	Pointer to the Schur complement, as CrsMatrix.
Epetra_SerialDenseMatrix *	DenseSchurComplement_
	Pointer to the Schur complement,as DenseMatrix.
const Epetra_LinearProblem *	Problem_
	Pointer to the linear problem to be solved.
Epetra_Map *	RedistrMap_
	Redistributed matrix.
Epetra_Import *	RedistrImporter_
	Redistributed importer (from Matrix().RowMatrixRowMap() to RedistrMatrix().RowMatrixRowMap()).
Epetra_CrsMatrix *	RedistrMatrix_
	Redistributed matrix (only if MaxProcs_ > 1).
Epetra_Map *	SerialMap_
	Map with all elements on process 0 (for solution and rhs).
Epetra_Import *	SerialImporter_
	Importer from Matrix.OperatorDomainMap() to SerialMap_.

---

Detailed Description

Amesos_Mumps: An object-oriented wrapper for CERFACS' MUMPS.

Amesos_Mumps is an interface to the CERFACS' sparse parallel direct solver MUMPS. Given an Epetra_RowMatrix A, and two Epetra_MultiVectors X and B, the solution with Amesos_Mumps reads as follows:

1. Epetra_LinearProblem Problem; Amesos_BaseSolver * Solver; Amesos Amesos_Factory;
2. Solver = Amesos_Factory.Create("Amesos_Mumps", Problem);
3. if( Solver == 0 ) cerr << "library not available" << endl;
4. Problem.SetMatrix(&A);
5. Solver->SymbolicFactorization();
6. Solver->NumericFactorization();
7. Problem.SetLHS(&X);
8. Problem.SetLHS(&B);
9. Solver->Solve();

A number of parameters is available to tune the performances of MUMPS. We refer to the Amesos Reference Guide for a detailed overview of these parameters. Here, we just recall that it is possible to solve the linear system on a subset of the processes contained in the Comm object of the Epetra_LinearProblem.

Amesos_Mumps accepts any Epetra_RowMatrix derived class. However, special functions are available for Epetra_CrsMatrix and Epetra_VbrMatrix objects.

The single-precision version of MUMPS can be used by enabling the option --enable-amesos-smumps. Note that this option overwrites --enable-amesos-mumps. The choice between single-precision and double-precision must be done at configuration (and compilation) time.

As Amesos is based on Epetra, and Epetra is only double-precision, we still require an Epetra_LinearProblem composed by a double-precision matrix, and two double-precision vectors. The solution vector is casted to double after solution. Single precision may be of interest if Amesos is used with ML, to solve the coarse problem (for which single-precision can be enough in term of numerical error, and usually save memory and CPU time).

Amesos_Mumps is based on Amesos_EpetraBaseSolver, that is derived from Amesos_BaseSolver. The main redistribution utilities, as well as a getrow function, is obtained by EpetraBaseSolver.

Warning:

This interface has been developed with MUMPS 4.3.1.

Author:

Marzio Sala, 9214

---

Constructor & Destructor Documentation

Amesos_Mumps::Amesos_Mumps (  const Epetra_LinearProblem &  LinearProblem  )

Amesos_Mumps Constructor. Creates an Amesos_Mumps instance, using an Epetra_LinearProblem,

Amesos_Mumps::~Amesos_Mumps (  void   )

Amesos_Mumps Destructor. Deletes an Amesos_Mumps object.

---

Member Function Documentation

int Amesos_Mumps::ComputeSchurComplement (  bool  flag, int  NumSchurComplementRows, int *  SchurComplementRows )

Returns the Schur complement matrix as an Epetra_CrsMatrix. Returns the (dense) Schur complement matrix as an Epetra_CrsMatrix. This matrix is defined on all the processes in the Epetra Communicator. However, it has rows on the host process only. If flag : if true, MUMPS will compute the Schur complement matrix, with respect to the (global) rows defined in the integer array SchurComplementRows, of size NumSchurComplementRows. Those two arrays are defined on the host only.

Epetra_CrsMatrix * Amesos_Mumps::GetCrsSchurComplement (   )

Returns the Schur complement in an Epetra_CrsMatrix on host only. Returns the Schur complement in an Epetra_CrsMatrix on host only. Note that no checks are performed to see whether this action is legal or not (that is, if the call comes after the solver has been invocated). Epetra_CrsMatrix must be freed by the user!

Epetra_SerialDenseMatrix * Amesos_Mumps::GetDenseSchurComplement (   )

Returns the Schur complement as a SerialDenseMatrix (on host only). Returns the Schur complement in an Epetra_SerialDenseMatrix on host only. Note that no checks are performed to see whether this action is legal or not (that is, if the call comes after the solver has been invocated). Epetra_SerialDenseMatrix must be freed by the user!

int* Amesos_Mumps::GetINFO (   )  [inline]

Gets the pointer to the INFO array (defined on all processes). Gets the pointer to the internally stored INFO array, of type int.

int* Amesos_Mumps::GetINFOG (   )  [inline]

Get the pointer to the INFOG array (defined on host only). Gets the pointer to the internally stored INFOG (defined on the host process only) array, of type int.

double* Amesos_Mumps::GetRINFO (   )  [inline]

Gets the pointer to the RINFO array (defined on all processes). Gets the pointer to the internally stored RINFO array, of type float if option --enable-amesos-smumps is enabled, double otherwise.

double* Amesos_Mumps::GetRINFOG (   )  [inline]

Gets the pointer to the RINFOG array (defined on host only). Gets the pointer to the internally stored RINFOG array (defined on the host process only), of type float if option --enable-amesos-smumps is enabled, double otherwise.

bool Amesos_Mumps::MatrixShapeOK (   )  const [inline, virtual]

Returns true if the solver can handle this matrix shape. Returns true if the matrix shape is one that the underlying sparse direct solver can handle. Classes that work only on square matrices should return false for rectangular matrices. Classes that work only on symmetric matrices whould return false for non-symmetric matrices. Implements Amesos_BaseSolver.

int Amesos_Mumps::NumericFactorization (   )  [virtual]

Performs NumericFactorization on the matrix A. In addition to performing numeric factorization on the matrix A, the call to NumericFactorization() implies that no change will be made to the underlying matrix without a subsequent call to NumericFactorization(). <br >Preconditions: GetProblem().GetOperator() != 0 (return -1) MatrixShapeOk(GetProblem().GetOperator()) == true (return -6) The non-zero structure of the matrix should not have changed since the last call to SymbolicFactorization(). (return -2 if the number of non-zeros changes) Other changes can have arbitrary consequences. The distribution of the matrix should not have changed since the last call to SymbolicFactorization() The matrix should be indexed from 0 to n-1, unless the parameter "Reindex" was set to "true" prior to the call to SymbolicFactorization(). (return -3 - if caught) The paremeter "Reindex" should not be set to "true" except on CrsMatrices. (return -4) The paremeter "Reindex" should not be set to "true" unless Amesos was built with EpetraExt, i.e. with --enable-epetraext on the configure line. (return -4) Internal errors retur -5. <br >Postconditions: Numeric Factorization will be performed (or marked to be performed) allowing Solve() to be performed correctly despite a potential change in in the matrix values (though not in the non-zero structure). Returns: Integer error code, set to 0 if successful. Implements Amesos_BaseSolver.

void Amesos_Mumps::PrintStatus (   )

Prints information about the factorization and solution phases. In the destruction phase, prints out some information furnished by MUMPS, like the amount of required memory, the MFLOPS.

void Amesos_Mumps::PrintTiming (   )

Prints timing information. In the destruction phase, prints out detailed information about the various phases: symbolic and numeric factorization, solution, gather/scatter for vectors and matrices.

int Amesos_Mumps::SetColScaling (  double *  ColSca  )  [inline]

Set column scaling. Use double precision vectors of size N (global dimension of the matrix) for column scaling. Parameters: ColSca  (In) - float pointer with --enable-amesos-smumps, double pointer otherwise.

int Amesos_Mumps::SetOrdering (  int *  PermIn  )  [inline]

Sets ordering. Use integer vectors of size N (global dimension of the matrix) as given ordering. PermIn must be defined on the host only, and allocated by the user, if the user sets ICNTL(7) = 1.

int Amesos_Mumps::SetParameters (  Teuchos::ParameterList &  ParameterList  )  [virtual]

Updates internal variables. <br >Preconditions: None. <br >Postconditions: Internal variables controlling the factorization and solve will be updated and take effect on all subseuent calls to NumericFactorization() and Solve(). All parameters whose value are to differ from the default values must be included in ParameterList. Parameters not specified in ParameterList revert to their default values. Returns: Integer error code, set to 0 if successful. Implements Amesos_BaseSolver.

int Amesos_Mumps::SetPrecscaling (  double *  ColSca, double *  RowSca )  [inline]

Set prescaling. Use double precision vectors of size N (global dimension of the matrix) as scaling for columns and rows. ColSca and RowSca must be defined on the host only, and allocated by the user, if the user sets ICNTL(8) = -1. Both input vectors are float with --enable-amesos-smumps, double otherwise.

int Amesos_Mumps::SetRowScaling (  double *  RowSca  )  [inline]

Set row scaling. Use double precision vectors of size N (global dimension of the matrix) for row scaling. Parameters: RowSca  (In) -float pointer with --enable-amesos-smumps, double pointer otherwise.

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

If set true, X will be set to the solution of AT X = B (not A X = B). If the implementation of this interface does not support transpose use, this method should return a value of -1. <br >Preconditions: SetTranspose() should be called prior to the call to SymbolicFactorization() If NumericFactorization() or Solve() is called after SetTranspose() without an intervening call to SymbolicFactorization() the result is implementation dependent. <br >Postconditions: The next factorization and solve will be performed with the new value of UseTranspose. Parameters: UseTranspose  -- (In) If true, solve AT X = B, otherwise solve A X = B. Returns: Integer error code, set to 0 if successful. Set to -1 if this implementation does not support transpose. Implements Amesos_BaseSolver.

int Amesos_Mumps::Solve (   )  [virtual]

Solves A X = B (or AT x = B). <br >Preconditions: GetProblem().GetOperator() != 0 (return -1) MatrixShapeOk(GetProblem().GetOperator()) == true (return -6) GetProblem()->CheckInput (see Epetra_LinearProblem::CheckInput() for return values) The non-zero structure of the matrix should not have changed since the last call to SymbolicFactorization(). The distribution of the matrix should not have changed since the last call to SymbolicFactorization() The matrix should not have changed since the last call to NumericFactorization(). <br >Postconditions: X will be set such that A X = B (or AT X = B), within the limits of the accuracy of the underlying solver. Returns: Integer error code, set to 0 if successful. Implements Amesos_BaseSolver.

int Amesos_Mumps::SymbolicFactorization (   )  [virtual]

Performs SymbolicFactorization on the matrix A. In addition to performing symbolic factorization on the matrix A, the call to SymbolicFactorization() implies that no change will be made to the non-zero structure of the underlying matrix without a subsequent call to SymbolicFactorization(). <br >Preconditions: GetProblem().GetOperator() != 0 (return -1) MatrixShapeOk(GetProblem().GetOperator()) == true (return -6) <br >Postconditions: Symbolic Factorization will be performed (or marked to be performed) allowing NumericFactorization() and Solve() to be called. Returns: Integer error code, set to 0 if successful. Implements Amesos_BaseSolver.

---

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

• Amesos_Mumps.h
• Amesos_Mumps.cpp

---