Getting Started

We describe the basics for building and applying MLD2P4 one-level and multi-level Schwarz preconditioners with the Krylov solvers included in PSBLAS [16]. The following steps are required:

1. Declare the preconditioner data structure. It is a derived data type, mld_xprec_ type, where x may be s, d, c or z, according to the basic data type of the sparse matrix (s = real single precision; d = real double precision; c = complex single precision; z = complex double precision). This data structure is accessed by the user only through the MLD2P4 routines, following an object-oriented approach.
2. Allocate and initialize the preconditioner data structure, according to a preconditioner type chosen by the user. This is performed by the routine mld_precinit, which also sets defaults for each preconditioner type selected by the user. The defaults associated to each preconditioner type are given in Table 1, where the strings used by mld_precinit to identify the preconditioner types are also given. Note that these strings are valid also if uppercase letters are substituted by corresponding lowercase ones.
3. Modify the aggregation parameters. This is performed by the routine mld_precset. This routine must be called only if the user wants to modify the default values of the parameters associated to the aggregation hierarchy construction. Examples of use of mld_precset are given in Section 5.1; a complete list of all the preconditioner parameters and their allowed and default values is provided in Section 6, Tables 2-6.
4. Build the aggregation hierarchy for a given matrix. This is performed by the routine mld_hierarchy_bld.
5. Modify the selected preconditioner type, by properly setting preconditioner parameters. This is performed by the routine mld_precset. This routine must be called only if the user wants to modify the default values of the parameters associated to the selected preconditioner type, to obtain a variant of the preconditioner. Examples of use of mld_precset are given in Section 5.1; a complete list of all the preconditioner parameters and their allowed and default values is provided in Section 6, Tables 2-6.
6. Build the preconditioner for a given matrix. This is performed by the routine mld_ml_prec_bld.
7. Apply the preconditioner at each iteration of a Krylov solver. This is performed by the routine mld_precaply. When using the PSBLAS Krylov solvers, this step is completely transparent to the user, since mld_precaply is called by the PSBLAS routine implementing the Krylov solver (psb_krylov).
8. Free the preconditioner data structure. This is performed by the routine mld_ precfree. This step is complementary to step 1 and should be performed when the preconditioner is no more used.

A detailed description of the above routines is given in Section 6. Examples showing the basic use of MLD2P4 are reported in Section 5.1.

Note that the Fortran 95 module mld_prec_mod, containing the definition of the preconditioner data type and the interfaces to the routines of MLD2P4, must be used in any program calling such routines. The modules psb_base_mod, for the sparse matrix and communication descriptor data types, and psb_krylov_mod, for interfacing with the Krylov solvers, must be also used (see Section 5.1).

Remark 1. The coarsest-level solver used by the default two-level preconditioner has been chosen by taking into account that, on parallel machines, it often leads to the smallest execution time when applied to linear systems coming from finite-difference discretizations of basic elliptic PDE problems, considered as standard tests for multi-level Schwarz preconditioners [3,4]. However, this solver does not necessarily correspond to the smallest number of iterations of the preconditioned Krylov method, which is usually obtained by applying a direct solver to the coarsest-level system, e.g. based on the LU factorization (see Section 6 for the coarsest-level solvers available in MLD2P4).

Table 1: Preconditioner types, corresponding strings and default choices.

TYPE	STRING	DEFAULT PRECONDITIONER
No preconditioner	'NOPREC'	Considered only to use the PSBLAS Krylov solvers with no preconditioner.
Diagonal	'DIAG'	--
Block Jacobi	'BJAC'	Block Jacobi with ILU(0) on the local blocks.
Additive Schwarz	'AS'	Restricted Additive Schwarz (RAS), with overlap 1 and ILU(0) on the local blocks.
Multilevel	'ML'	Multi-level hybrid preconditioner (additive on the same level and multiplicative through the levels), with pre- and post-smoothing. Target aggregation size: cubic root of the size at the finest level. Smoother: RAS with overlap 1 and ILU(0) on the local blocks. Aggregation: decoupled smoothed aggregation with threshold $\theta = 0$. Coarsest matrix: distributed among the processors. Coarsest-level solver: 4 sweeps of the block-Jacobi solver, with LU or ILU factorization of the blocks (MUMPS, or UMFPACK for the double precision versions and SuperLU for the single precision ones, if the packages have been installed; ILU(0), otherwise).