ML: Multi Level Preconditioning Package
ML is a large package. The following documents are suggested to ML users:
- Sandia report SAND2004-4819 (ML 3.1 Smoothed Aggregation User's Guide, by M. Sala, J. Hu and R. Tuminaro) introduces to the use of ML. The guide is focused on smoothed aggregation multilevel methods. (However, ML can also be used for geometric multilevel methods.). The guide can be downloaded from the "documentation" page.
- The doxygen documentation is suggested for an up-to-date overview of the C++ functionalities of ML. ML has an Epetra interface, and can be used to define black-box preconditioners for Epetra_RowMatrix's. The doxygen documentation covers the ML/Epetra interface, and does NOT cover the C source files.
- A developers' guide is available in the ml/doc subdirectory (Sandia report number SAND2004-4821).
- Consult also the ChangeLog and README files.
Probably, the best way to understand ML is to use it. Several examples are provided in the Trilinos/packages/ml/examples subdirectories. Users are suggested to compile and run these examples. Often, a copy-and-paste approach is good enough to start with ML. This is particularly true for the ML/Epetra interface.
Several examples are distributed within ml. You can browse the source file of the following examples:
To take advantage of the ML/Epetra interface, ML must be configured with the following options:
It is suggested to enable the Amesos interface (
--enable-amesos). Amesos is a Trilinos package that interfaces with various serial and parallel sparse direct solvers. Besides, it contains a simple serial sparse direct solver (KLU), that is quite good for small matrices.
New users interested in the ML/Epetra interface should take a look to the following classes (both in the ML_Epetra namespace):
Detailed examples are reported in:
This documentation is targeted to the ML_Epetra::MultiLevelPreconditioner class. It is very useful to have a list of the available parameters for a given option. This can be in obtained from the comments of:
The following structure are used by ML:
- for smoothers: ML_Epetra::MultiLevelPreconditioner::SetSmoothers()
- for Maxwell smoothers: ML_Epetra::MultiLevelPreconditioner::SetSmoothersMaxwell();
- for the coarse solver: ML_Epetra::MultiLevelPreconditioner::SetCoarse();
- for default values: ML_Epetra::SetDefaults().
ML is bases on a particular (and very flexible) matrix format, defined by the ML_Operator struct. A set of conversion utilities exists to:
- ML_Struct (aliased simply as ML) contains the main information about the ML hierarchy;
- ML_Aggregate_Struct (aliased as ML_Aggregate) contains the main information about the aggregates (for smoothed aggregates only)
- ML_Operator_Struct (aliased as ML_Operator) defined the ML's internal matrix format;
- classes MultiLevelOperator and MultiLevelPreconditioner should be use to define AztecOO preconditioners.
All the conversion functions are declared in file ml_epetra_utils.h.
If configured with options
--enable-teuchos, ML can take advantage of Amesos to solve the coarse problem.
Details about the ML/Amesos interface are reported in file ml_amesos_wrap.h.
If configured with options
- ML supports directly SuperLU (serial version) and SuperLU_DIST (distributed version). These interfaces are deprecated in favor of the Amesos interface (although still working).
--enable-teuchos, ML can use IFPACK to define ILU-type smoothers.
Details about the ML/IFPACK interface are reported in file ml_ifpack_wrap.h.
If configured with options
--enable-teuchos, ML can use Anasazi for eigenvalue computations.
The user can:
- use Anasazi to estimate the maximum eigenvalue of a given level matrix (for smoothed aggregation);
- use Anasazi to compute the low-convergence modes, and filter them;
- use Anasazi to compute the field-of-values of a non-symmetric operator, and use this information to improve smoothed aggregation for highly non-symmetric systems.
Details about the ML/Anasazi interface are reported in file ml_anasazi.h, and in the ML_Anasazi namespace.
It is possible to instruct ML_Epetra::MultiLevelPreconditioner to print out the process ID, so that one can attach to the desired process. One can proceed as follows:
- ML also have an interface to ARPACK and PARPACK.
- define the environmental 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. Few information about the ID number of each process will be showed.
- in another terminal, attach to the desired process.
- insert one character to let the code continue, and debug as required.
(see also the documentation of method ML_Epetra::MultiLevelPreconditioner::BreakForDebugger()).
If ML is compiled with -DML_MEM_CHECK, the destruction of ML_Epetra::MultiLevelPreconditioner() will verify that memory has not been corrupted, and that no memory leak occurs. Note that this option may be computationally expensive, and it is not recommended for performance evaluations.
Consult the ChangeLog file. The README file gives some other information about ML.
Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
license for use of this work by or on behalf of the U.S. Government.
This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
Generated on Thu Sep 18 12:42:33 2008 for ML by 220.127.116.11