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_RowMatrixRowMatrix () const
 Returns a reference to the internally stored RowMatrix.
const Epetra_BlockMapMap () const
 Returns a reference to RowMatrix->Map().
int NumGlobalRows () const
 Returns the global number of rows in the matrix.
int NumGlobalCols () const
 Returns the global number of columns in the matrix.
int NumMyRows () const
 Returns the local number of rows in the matrix.
int NumMyCols () const
 Returns the local number of columns in the matrix.
Constructors.
 MultiLevelPreconditioner (const Epetra_RowMatrix &RowMatrix, const bool ComputePrec=true)
 Constructs a MultiLevelPreconditioner with default values.
 MultiLevelPreconditioner (const Epetra_RowMatrix &RowMatrix, const Teuchos::ParameterList &List, const bool ComputePrec=true)
 Constructs a MultiLevelPreconditioner. Retrieves parameters from List.
 MultiLevelPreconditioner (ML_Operator *Operator, const Teuchos::ParameterList &List, const bool ComputePrec=true)
 Constructs a MultiLevelPreconditioner from an ML_Operator. Retrieves parameters from List.
 MultiLevelPreconditioner (const Epetra_RowMatrix &EdgeMatrix, const Epetra_RowMatrix &GradMatrix, const Epetra_RowMatrix &NodeMatrix, const Teuchos::ParameterList &List, const bool ComputePrec=true)
 MultiLevelPreconditioner constructor for Maxwell's equations.
 MultiLevelPreconditioner (const Epetra_RowMatrix &CurlCurlMatrix, const Epetra_RowMatrix &MassMatrix, const Epetra_RowMatrix &TMatrix, const Epetra_RowMatrix &NodeMatrix, const Teuchos::ParameterList &List, const bool ComputePrec=true)
 MultiLevelPreconditioner constructor for Maxwell's equations.
 MultiLevelPreconditioner (const Epetra_MsrMatrix &EdgeMatrix, ML_Operator *GradMatrix, AZ_MATRIX *NodeMatrix, int *proc_config, const Teuchos::ParameterList &List, const bool ComputePrec=true)
 MultiLevelPreconditioner constructor for Maxwell's equations.
Destructor.
virtual ~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::ParameterListGetList ()
 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 ReComputePreconditioner ()
 Recomputed the preconditioner (not implemented for Maxwell).
void Print (const char *whichHierarchy="main")
 Print the individual operators in the multigrid 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_CommComm () const
 Returns a pointer to the Epetra_Comm communicator associated with this operator.
const Epetra_MapOperatorDomainMap () const
 Returns the Epetra_Map object associated with the domain of this operator.
const Epetra_MapOperatorRangeMap () 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 AnalyzeHierarchy (const bool AnalyzeMatrices, const int PreCycles, const int PostCycles, const int MLCycles)
 Cheap analysis of each level matrix.
int AnalyzeSmoothers (const int NumPreCycles=1, const int NumPostCycles=1)
 Analyze the effect of each level's smoother on a random vector.
int AnalyzeCoarse ()
 Analyze the effect of the coarse solver on a random vector.
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 MLGetML (const int WhichML=-1) const
 Returns a pointer to the internally stored ml pointer.
bool SolvingMaxwell () const
const ML_AggregateGetML_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)
 Generic interface to visualization methods.
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.
int ReadXML (const string &FileName)
 Reads a parameter list from an XML file.

Detailed Description

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

The class ML_Epetra::MultiLevelPreconditioner defines a black-box algebraic multigrid preconditioner for matrices derived from an Epetra_RowMatrix. The resulting preconditioner can be used in AztecOO, and in any other solver that accepts Epetra_Operator derived objects, and applies 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:

The following options are suggested:

Some parts of this class need the following options:

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 products, 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:

Note:
Namespace ML_Epetra contains another Epetra_Operator derived class, ML_Epetra::MultiLevelOperator.
Defaults parameters can be specified using function SetDefaults().

Author:
Marzio Sala, SNL 9214


Constructor & Destructor Documentation

ML_Epetra::MultiLevelPreconditioner::MultiLevelPreconditioner const Epetra_RowMatrix EdgeMatrix,
const Epetra_RowMatrix GradMatrix,
const Epetra_RowMatrix NodeMatrix,
const Teuchos::ParameterList List,
const bool  ComputePrec = true
 

MultiLevelPreconditioner constructor for Maxwell's equations.

Takes the stiffness and mass terms of the matrix combined.

Parameters:
EdgeMatrix - (In) Linear matrix to be solved.
GradMatrix - (In) Node-to-edge connectivity matrix, a.k.a, topological gradient
NodeMatrix - (In) Auxiliary nodal finite element matrix
List - (In) Teuchos parameter list containing solver options.
ComputePrec - (In) Optional argument that specifies whether to create preconditioner immediately. Default is true.

ML_Epetra::MultiLevelPreconditioner::MultiLevelPreconditioner const Epetra_RowMatrix CurlCurlMatrix,
const Epetra_RowMatrix MassMatrix,
const Epetra_RowMatrix TMatrix,
const Epetra_RowMatrix NodeMatrix,
const Teuchos::ParameterList List,
const bool  ComputePrec = true
 

MultiLevelPreconditioner constructor for Maxwell's equations.

Takes the stiffness and mass terms of the matrix separately.

Parameters:
CurlCurlMatrix - (In) The curl-curl (stiffness) term of the matrix to be solved.
MassMatrix - (In) The mass term of the matrix to be solved.
GradMatrix - (In) Node-to-edge connectivity matrix, a.k.a, topological gradient
NodeMatrix - (In) Auxiliary nodal finite element matrix
List - (In) Teuchos parameter list containing solver options.
ComputePrec - (In) Optional argument that specifies whether to create preconditioner immediately. Default is true.

ML_Epetra::MultiLevelPreconditioner::MultiLevelPreconditioner const Epetra_MsrMatrix EdgeMatrix,
ML_Operator GradMatrix,
AZ_MATRIX *  NodeMatrix,
int *  proc_config,
const Teuchos::ParameterList List,
const bool  ComputePrec = true
 

MultiLevelPreconditioner constructor for Maxwell's equations.

Takes the stiffness and mass terms of the matrix combined. The edge matrix is of type Epetra_Msr, a light-weight wrapper for old-style Aztec MSR matrices. This is intended as transition code for Aztec users.

Use at your own risk!

Parameters:
EdgeMatrix - (In) Linear matrix to be solved.
GradMatrix - (In) Node-to-edge connectivity matrix, a.k.a, topological gradient
NodeMatrix - (In) Auxiliary nodal finite element matrix
proc_config - (In) Aztec array specifying processor layout.
List - (In) Teuchos parameter list containing solver options.
ComputePrec - (In) Optional argument that specifies whether to create preconditioner immediately. Default is true.


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 )
  • set "debug mode" to be true in the ML parameter list
  • 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)

void ML_Epetra::MultiLevelPreconditioner::Print const char *  whichHierarchy = "main"  ) 
 

Print the individual operators in the multigrid hierarchy.

Print the individual operators in the multigrid hierarchy.

Parameters:
whichHierarchy (In) By default, this method prints the main multigrid hierarchy. If solving Maxwell's equations, and this is set to anything other than "main", the auxiliary node hierarchy will print.

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:
Generated on Thu Sep 18 12:38:46 2008 for ML by doxygen 1.3.9.1