ML_Epetra::MultiLevelPreconditioner Class Reference

MultiLevelPreconditioner: a class to define black-box multilevel preconditioners using aggregation methods. More...

#include <ml_MultiLevelPreconditioner.h>

Inheritance diagram for ML_Epetra::MultiLevelPreconditioner:

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

Public Member Functions
int	DestroyPreconditioner ()
	Destroys all structures allocated in ComputePreconditioner() if the preconditioner has been computed.
const Epetra_BlockMap &	Map () const
	Returns a reference to RowMatrix->Map().
int	NumGlobalRows () const
int	NumGlobalCols () const
int	NumMyRows () const
int	NumMyCols () const
Constructors.
	MultiLevelPreconditioner (const Epetra_RowMatrix &RowMatrix, const bool ComputePrec)
	Constructs an MultiLevelPreconditioner with default values.
	MultiLevelPreconditioner (const Epetra_RowMatrix &RowMatrix, const Teuchos::ParameterList &List, const bool ComputePrec=true)
	Constructs an MultiLevelPreconditioner. Retrives parameters from List.
	MultiLevelPreconditioner (ML_Operator *Operator, const Teuchos::ParameterList &List, const bool ComputePrec=true)
	Constructs an MultiLevelPreconditioner from an ML_Operator. Retrives parameters from List.
	MultiLevelPreconditioner (const Epetra_RowMatrix &EdgeMatrix, const Epetra_RowMatrix &TMatrix, const Epetra_RowMatrix &NodeMatrix, const Teuchos::ParameterList &List, const bool ComputePrec=true)
	Constructs an MultiLevelPreconditioner for Maxwell equations. Retrives parameters from List.
	MultiLevelPreconditioner (const Epetra_MsrMatrix &EdgeMatrix, ML_Operator *ML_TMatrix, AZ_MATRIX *AZ_NodeMatrix, int *proc_config, const Teuchos::ParameterList &List, const bool ComputePrec)
	Constructs an MultiLevelPreconditioner for Maxwell equations. Retrives parameters from List.
Destructor.
	~MultiLevelPreconditioner ()
	Destroys the preconditioner.
Query functions
const char *	Label () const
	Prints label associated to this object.
void	PrintUnused () const
	Prints unused parameters in the input ParameterList on standard output. */.
void	PrintUnused (ostream &os) const
	Prints unused parameters in the input ParameterList on the specified stream.
void	PrintUnused (const int MyPID) const
	Prints unused parameters in the input ParameterList to cout on proc MyPID.
Teuchos::ParameterList &	GetList ()
	Gets a reference to the internally stored parameters' list.
Teuchos::ParameterList	GetOutputList ()
void	PrintList (int MyPID)
	Prints on cout the values of the internally stored parameter list for processor MyPID.
int	SetParameterList (const Teuchos::ParameterList &List)
	Copies List into the internally stored parameter list object.
Mathematical functions.
int	Apply (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Apply the inverse of the preconditioner to an Epetra_MultiVector (NOT AVAILABLE).
int	ApplyInverse (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
	Apply the preconditioner to an Epetra_MultiVector X, puts the result in Y.
Atribute access functions
int	ComputePreconditioner (const bool CheckFiltering=false)
	Computes the multilevel hierarchy.
int	ComputeAdaptivePreconditioner (int TentativeNullSpaceSize, double *TentativeNullSpace)
int	IsPreconditionerComputed () const
	Queries whether multilevel hierarchy has been computed or not.
int	SetOwnership (bool ownership)
	Sets ownership.
int	SetUseTranspose (bool UseTranspose)
	Sets use transpose (not implemented).
double	NormInf () const
	Returns the infinity norm (not implemented).
bool	UseTranspose () const
	Returns the current UseTranspose setting.
bool	HasNormInf () const
	Returns true if the this object can provide an approximate Inf-norm, false otherwise.
const Epetra_Comm &	Comm () const
	Returns a pointer to the Epetra_Comm communicator associated with this operator.
const Epetra_Map &	OperatorDomainMap () const
	Returns the Epetra_Map object associated with the domain of this operator.
const Epetra_Map &	OperatorRangeMap () const
	Returns the Epetra_Map object associated with the range of this operator.
debugging and other utilities
int	BreakForDebugger ()
	Stops the code, waiting for a debugger to attach.
int	PrintStencil2D (const int nx, const int ny, int NodeID=-1, const int EquationID=0)
	Prints the computational stencil for the specified row and equation (for 2D Cartesian grids only).
int	AnalyzeSmoothersSparse (const int NumPreCycles=1, const int NumPostCycles=1)
	Analyze the effect of each level's smoother on a random vector.
int	AnalyzeSmoothersDense (const int NumPreCycles=1, const int NumPostCycles=1, const int MaxSize=1024)
	Analyze the effect of each level's smoother on a random vector.
int	AnalyzeMatrixCheap ()
	Cheap analysis of each level matrix.
int	AnalyzeMatrixEigenvaluesSparse (char *MatVec, bool IsSymmetric=false)
	Compute the lowest and largest magniture eigenvalues of fine-level matrix.
int	AnalyzeMatrixEigenvaluesDense (char *MatVec, bool IsSymmetric=false)
	Compute the lowest and largest magniture eigenvalues of fine-level matrix.
int	AnalyzeCycle (const int NumCycles=1)
	Analyze the effect of the ML cycle on a random vector.
int	TestSmoothers (Teuchos::ParameterList &InputList, const bool IsSymmetric=false)
	Test several smoothers on fine-level matrix.
int	TestSmoothers (const bool IsSymmetric=false)
	Test several smoothers on fine-level matrix using the current parameters.
const ML *	GetML () const
	Returns a pointer to the internally stored ml pointer.
const ML_Aggregate *	GetML_Aggregate () const
	Returns a pointer to the internally stored agg pointer.
int	Visualize (bool VizAggre, bool VizPreSmoother, bool VizPostSmoother, bool VizCycle, int NumApplPreSmoother, int NumApplPostSmoother, int NumCycleSmoother)
int	VisualizeAggregates ()
	Visualizes the shape of the aggregates.
int	VisualizeSmoothers (int NumPrecCycles=1, int NumPostCycles=1)
	Visualizes the effect of smoothers on a random vector.
int	VisualizeCycle (int NumCycles=1)
	Visualizes the effect of the ML cycle on a random vector.

---

Detailed Description

MultiLevelPreconditioner: a class to define black-box multilevel preconditioners using aggregation methods.

Class ML_Epetra::MultiLevelPreconditioner defined black-box algebraic multilevel preconditioners of matrices defined as Epetra_RowMatrix derived objects. The resulting preconditioner can be used in AztecOO, and in any other solver that accepts Epetra_Operator derived objects, and apply the action of the given Epetra_Operator using ApplyInverse().

Please refer to the user's guide for a detailed introduction to this class, examples, and description of input parameters.

This file requires ML to be configured with the following options:

• --enable-epetra
• --enable-teuchos

The following option is suggested:

• --enable-amesos
• --enable-ifpack

Some part of this class needs the following options:

• --enable-aztecoo
• --enable-anasazi

It is important to note that ML is more restrictive than Epetra for the definition of maps. It is required that RowMatrixRowMap() is equal to OperatorRangeMap(). This is because ML needs to perform matrix-vector product, as well as getrow() functions, on the same data distribution.

Also, for square matrices, OperatorDomainMap() must be as OperatorRangeMap().

Several examples are provided in the examples subdirectories:

• ml_preconditioner.cpp is an introductory example;
• ml_2level_DD.cpp shows how to define a 2-level domain decomposition preconditioner using this class;
• ml_viz.cpp details how to visualize the aggregates;
• ml_maxwell.cpp reports how to use this class for Maxwell problems.

Note:

Namespace ML_Epetra contains another Epetra_Operator derived class, ML_Epetra::MultiLevelOperator.

• you should use MultiLevelOperator when your code already defines the required ML objects, with the optimal choice of parameters, and you just want to wrap the already defined ML preconditioners for AztecOO problems;
• you should use MultiLevelPreconditioner when you have an Epetra_RowMatrix, and you don't want to code the conversion to ML_Operator, the creation of the hierarchy and the aggregates, and/or you want to experiment various combinations of the parameters, simply changing some parameters in a Teuchos::ParameterList.

Defaults parameters can be specified using function SetDefaults().

Warning:

The Maxwell interface is still under development.

Author:

Marzio Sala, SNL 9214

---

Constructor & Destructor Documentation

ML_Epetra::MultiLevelPreconditioner::MultiLevelPreconditioner (  const Epetra_RowMatrix &  EdgeMatrix, const Epetra_RowMatrix &  TMatrix, const Epetra_RowMatrix &  NodeMatrix, const Teuchos::ParameterList &  List, const bool  ComputePrec = true )

Constructs an MultiLevelPreconditioner for Maxwell equations. Retrives parameters from List. Constructs an MultiLevelPreconditioner for Maxwell equations. The constructor requires the edge matrix, the connectivity matrix T, the nodal matrix.

ML_Epetra::MultiLevelPreconditioner::MultiLevelPreconditioner (  const Epetra_MsrMatrix &  EdgeMatrix, ML_Operator *  ML_TMatrix, AZ_MATRIX *  AZ_NodeMatrix, int *  proc_config, const Teuchos::ParameterList &  List, const bool  ComputePrec )

Constructs an MultiLevelPreconditioner for Maxwell equations. Retrives parameters from List. Constructs an MultiLevelPreconditioner for Maxwell equations. The constructor requires the edge matrix, the connectivity matrix T, the nodal matrix.

---

Member Function Documentation

int ML_Epetra::MultiLevelPreconditioner::BreakForDebugger (   )

Stops the code, waiting for a debugger to attach. BreakForDebugger() is useful when the user wants to attach to the running process(es). This is a very easy task for serial runs -- just run gdb. Parallel runs may result more problematic. In this case, one can proceed as follows: define the enviromental variable ML_BREAK_FOR_DEBUGGER (example, in BASH, export ML_BREAK_FOR_DEBUGGER=1 ) run the parallel code on a terminal (example, mpirun -np 4 ml_example.exe ) the code will stop in the first call to ComputePreconditioner(). This may occur in the construction phase. Some information about the ID number of each process will be shown. in another terminal, attach to the desired process. insert one character to let the code continue, and debug as required.

int ML_Epetra::MultiLevelPreconditioner::ComputePreconditioner (  const bool  CheckFiltering = false  )

Computes the multilevel hierarchy. Computes the multilevel hierarchy. This function retrives the user's defines parameters (as specified in the input ParameterList), or takes default values otherwise, and creates the ML objects for aggregation and hierarchy. Allocated data can be freed used DestroyPreconditioner(), or by the destructor, In a Newton-type procedure, several linear systems have to be solved, Often, these systems are not too different. In this case, it might be convenient to keep the already computed preconditioner (with hierarchy, coarse solver, smoothers), and use it to precondition the next linear system. ML offers a way to determine whether the already available preconditioner is "good enough" for the next linear system. The user should proceed as follows: define "adaptive: enable" == true solve the first linear system. ML tries to estimate the rate of convergence, and record it; change the values of the linear system matrix (but NOT its structure) compute the new preconditioner as ComputePreconditioner(true) It is supposed that the pointer to the Epetra_RowMatrix remains constant. Currently, it is not possible to modify this pointer (other than creating a new preconditioner)

int ML_Epetra::MultiLevelPreconditioner::PrintStencil2D (  const int  nx, const int  ny, int  NodeID = -1, const int  EquationID = 0 )

Prints the computational stencil for the specified row and equation (for 2D Cartesian grids only). For problems defined on 2D Cartesian grids (with node numbering increasing along the x-axis), this function prints out the stencil in an intelligible form. Parameters: nx  (In) : number of nodes along the X-axis ny  (In) : number of nodes along the Y-axis NodeID  (In) : (local) ID of node that will be used to print the stencil. If set to -1, the code will automatically chose an internal node. Default: -1. EquationID  (In) : ID of the equation that will be used to print the stencil (default = 0)

void ML_Epetra::MultiLevelPreconditioner::PrintUnused (  const int  MyPID  )  const

Prints unused parameters in the input ParameterList to cout on proc MyPID. Mispelled parameters are simply ignored. Therefore, it is often the best choice to print out the parameters that have not been used in the construction phase. Parameters: MyPID  (In) : ID of process that should print the unused parameters.

---

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

• ml_MultiLevelPreconditioner.h
• ml_MultiLevelPreconditioner.cpp
• ml_MultiLevelPreconditioner_Adapt.cpp
• ml_MultiLevelPreconditioner_Analyze.cpp
• ml_MultiLevelPreconditioner_Aux.cpp
• ml_MultiLevelPreconditioner_Filtering.cpp
• ml_MultiLevelPreconditioner_NullSpace.cpp
• ml_MultiLevelPreconditioner_Smoothers.cpp
• ml_MultiLevelPreconditioner_Test.cpp
• ml_MultiLevelPreconditioner_Viz.cpp

---