ML: Multi Level Preconditioning Package
Version of the Day
ML is a large package. The following documents are suggested for ML users:
- "ML 5.0 Smoothed Aggregation User's Guide", Sandia report SAND2006-2649, by M. Gee, J. Hu, M. Sala, C. Siefert and R. Tuminaro. This report introduces how to use 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 provides 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, but does NOT cover the C source files.
- A developers' guide is available in the ml/doc subdirectory (Sandia report number SAND2004-4821).
- 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:
--enable-epetra
--enable-teuchos
We suggest enabling the Amesos interface (--enable-amesos
). Amesos is a Trilinos package that interfaces with various serial and parallel sparse direct solvers. Morever, 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:
- 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 used to define AztecOO preconditioners.
ML is bases on a particular (and very flexible) matrix format, defined by the ML_Operator struct. A set of conversion utilities exists to:
- convert an ML_Operator into an Epetra CrsMatrix with ML_Operator2EpetraCrsMatrix()
- convert (wrap) an Epetra_RowMatrix into an ML_Operator with EpetraMatrix2MLMatrix(). This is a light-weight conversion, as a suitable wrapper is created. This means that data are still stored in the original Epetra_RowMatrix. Functions Epetra_ML_comm_wrapper(), Epetra_ML_getrow() and Epetra_ML_matvec() are used to perform the getrow, data exchange and matrix-vector product.
All the conversion functions are declared in file ml_epetra_utils.h.
If configured with options
--enable-amesos
--enable-epetra
--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.
- Note:
- ML supports directly SuperLU (serial version) and SuperLU_DIST (distributed version). These interfaces are deprecated in favor of the Amesos interface (although still working).
If configured with options
--enable-ifpack
--enable-epetra
--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-anasazi
--enable-epetra
--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.
- Note:
- ML also have an interface to ARPACK and PARPACK.
An object-oriented layer based on ML, called
MLAPI, can be used to access most of the ML capabilites in a very way. Click
Overview of MLAPI for more details.
ML is accessible from Python through the PyTrilinos package. Using PyTrilinos, ML can be used to create black-box preconditioners based on smoothed aggregation for both serial and parallel runs, using a standard Python interpreter. Please refer to the PyTrilinos
homepage for more details.
Adapters are available for using ML with the Thyra solver components. See
ML/Thyra adapters.
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:
- define the environmental variable ML_BREAK_FOR_DEBUGGER (example, in BASH, export ML_BREAK_FOR_DEBUGGER=1 ), or create a file called
ML_debug_now
in the directory of the executable. - 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
USA