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 can be used for both serial and parallel computations.
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:
Equivalently, one vector can be deleted. For example, to delete the second multivector, one can write
meaning that now
V
contains just one vector.
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
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
which is instead an expensive operation, as new memory needs to be allocated, then all elements in C need to be copied in B.
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.
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.