Where to find documentation

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.

Examples source code

Several examples are distributed within ml. You can browse the source file of the following examples:

mlguide.c is the simplest ML (serial) example;
mlguide_par.c is the parallel counterpart of mlguide.c.
ml_aztec_simple.c gives an example of the ML/Aztec C interface;
ml_operator.cpp presents the use of the MultiLevelOperator class (see also section Example of use of ML_Epetra::MultiLevelOperator);
ml_preconditioner.cpp details the use of ML as a black-box preconditionerr (see also section Quick introduction to the ML/Epetra interface and section Example of use ML_Epetra::MultiLevelPreconditioner);
ml_2level_DD.cpp describes how to define domain decomposition preconditioners using ML.
ml_viz.cpp describes how to visualize the aggregates;
ml_analyze.cpp shows how ML can be used to analyze the performances of a the preconditioner on a given linear system;
ml_read_maxwell.cpp outlines the use of ML to solve the Maxwell equations.

Quick introduction to the ML/Epetra interface

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):

ML_Epetra::MultiLevelPreconditioner (defined in file ml_epetra_preconditioner.h)
ML_Epetra::MultiLevelOperator (defined in file ml_epetra_operator.h)
Function ML_Epetra::SetDefaults() can be used to set the default values.

Detailed examples are reported in:

The ML_Epetra::MultiLevelPreconditioner class

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:

for smoothers: ML_Epetra::MultiLevelPreconditioner::SetSmoothers()
for the coarse solver: ML_Epetra::MultiLevelPreconditioner::SetCoarse();
for default values: ML_Epetra::SetDefaults().

Main Structures of ML

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.

Conversion utilities from/to Epetra matrices.

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.

ML interface to Amesos

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).

ML interface to IFPACK

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.

ML interface to Anasazi

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.

Overview of MLAPI

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 for Python Applications

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.

ML/Thyra adapters

Adapters are available for using ML with the Thyra solver components. See ML/Thyra adapters.

Debugging Utilities

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.

(Incomplete) History of visible changes

Consult the ChangeLog file. The README file gives some other information about ML.

Copyright

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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
USA

Table of Contents