Overview of MLAPI

Table of contents

• Introduction to MLAPI
• Memory Management
• Use of MultiVector
• Available Preconditioners
• Interface with Epetra Objects

Introduction to MLAPI

The MLAPI are the Application Program Interface of ML. MLAPI defines a MATLAB-like environment for rapid prototyping of new multilevel preconditioners, usually of algebraic type.

All MLAPI objects are defined in the MLAPI namespace. The most important objects are:

• MLAPI::Space, which defines the data layout;
• MLAPI::Operator, the basic wrapper of ML_Operator and Epetra_RowMatrix objects;
• MLAPI::InverseOperator, which defined smoothers and coarse grid solvers;
• MLAPI::MultiVector, which contains one vector, or a collection of vectors, all sharing the same space.

MLAPI can be used for both serial and parallel computations.

Use of MultiVector

Class MLAPI::MultiVector contains one or more vectors. The general usage is as follows:

Space MySpace(128);
MultiVector V;
int NumVectors = 1;
V.Reshape(V, NumVectors);

A new vector can be added to the already allocated ones as follows:

V.Add();

Equivalently, one vector can be deleted. For example, to delete the second multivector, one can write

V.Delete(2);

meaning that now V contains just one vector.

Memory Management

One of the most powerful feature of C and C++ if the capability of allocating memory. Unfortunately, this is also the area where most bugs are found – not to mention memory leaks. We have adopted smart pointers to manage memory. MLAPI objects should never be allocated using new, and therefore never free them using delete. The code will automatically delete memory when it is no longer referenced by any object. Besides, functions or methods that need to return MLAPI objects, should always return an instance of the required object, and not a pointer or a reference.

Let us consider three generic MLAPI objects. The assignment A = B means the following: all smart pointers contained by B are copied in A, both A and B point to the same memory location. However, A and B are not aliases: we can still write

B = C

meaning that A contains what was contained in B, and both B and C point to the same memory location. Should we need to create a copy of C in B, we will use the instruction

B = Duplicate(C)

which is instead an expensive operation, as new memory needs to be allocated, then all elements in C need to be copied in B.

Available Preconditioners

Although MLAPI is design to be a framework for development of new preconditioners, two classes already defines ready-to-use preconditioners:

• MLAPI::MultiLevelSA is a classical smoothed aggregation preconditioner, which roughly behaves like class ML_Epetra::MultiLevel. However, the list of supported parameters is remarkably shorter. This class is meant as an example of usage of MLAPI for the definition of smoothed aggregation preconditioners;
• MLAPI::MultiLevelAdaptiveSA implements adaptive smoothed aggregation.
• example TwoLevelDDAdditive.cpp shows how to define a two-level domain decomposition preconditioner. This class shows how to define adaptive smoothed aggregation preconditioners.

Interface with Epetra Objects

Any Epetra_RowMatrix derived class can be wrapped as an MLAPI::Operator. (However, some restrictions apply, please check you Epetra_Map's for more details.)

An MLAPI::InverseOperator (and therefore preconditioners MLAPI::MultiLevelSA and MLAPI::MultiLevelAdaptiveSA) can be easily wrapped as an Epetra_Operator derived class, then used within, for instance, AztecOO. An example is reported in EpetraInterface.cpp.