diff --git a/docs/html/index.html b/docs/html/index.html
index 3a70fdf3..82c86e2e 100644
--- a/docs/html/index.html
+++ b/docs/html/index.html
@@ -23,18 +23,18 @@ original version by: Nikos Drakos, CBLU, University of Leeds
diff --git a/docs/html/node11.html b/docs/html/node11.html
index 3036675d..6b586910 100644
--- a/docs/html/node11.html
+++ b/docs/html/node11.html
@@ -18,7 +18,7 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
+
@@ -26,26 +26,26 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
-
- Next: Next: AMG preconditioners
- Up: Up: userhtml
- Previous: Previous: Example and test programs
- Contents
@@ -55,47 +55,51 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Multigrid Background
Multigrid preconditioners, coupled with Krylov iterative
solvers, are widely used in the parallel solution of large and sparse linear systems,
because of their optimality in the solution of linear systems arising from the
discretization of scalar elliptic Partial Differential Equations (PDEs) on regular grids.
Optimality, also known as algorithmic scalability, is the property
of having a computational cost per iteration that depends linearly on
the problem size, and a convergence rate that is independent of the problem size.
Multigrid preconditioners are based on a recursive application of a two-grid process
consisting of smoother iterations and a coarse-space (or coarse-level) correction.
The smoothers may be either basic iterative methods, such as the Jacobi and Gauss-Seidel ones,
or more complex subspace-correction methods, such as the Schwarz ones.
The coarse-space correction consists of solving, in an appropriately chosen
coarse space, the residual equation associated with the approximate solution computed
by the smoother, and of using the solution of this equation to correct the
previous approximation. The transfer of information between the original
(fine) space and the coarse one is performed by using suitable restriction and
prolongation operators. The construction of the coarse space and the corresponding
transfer operators is carried out by applying a so-called coarsening algorithm to the system
matrix. Two main approaches can be used to perform coarsening: the geometric approach,
which exploits the knowledge of some physical grid associated with the matrix
and requires the user to define transfer operators from the fine
to the coarse level and vice versa, and the algebraic approach, which builds
the coarse-space correction and the associate transfer operators using only matrix
information. The first approach may be difficult when the system comes from
discretizations on complex geometries;
furthermore, ad hoc one-level smoothers may be required to get an efficient
interplay between fine and coarse levels, e.g., when matrices with highly varying coefficients
are considered. The second approach performs a fully automatic coarsening and enforces the
interplay between fine and coarse level by suitably choosing the coarse space and
the coarse-to-fine interpolation (see, e.g., [3,23,21] for details.)
MLD2P4 uses a pure algebraic approach, based on the smoothed
aggregation algorithm [2,25],
for building the sequence of coarse matrices and transfer operators,
starting from the original one.
A decoupled version of this algorithm is implemented, where the smoothed
aggregation is applied locally to each submatrix [24].
A brief description of the AMG preconditioners implemented in MLD2P4 is given in
Sections 4.1-4.3. For further details the reader
is referred to [4,5,7,8].
We note that optimal multigrid preconditioners do not necessarily correspond
to minimum execution times in a parallel setting. Indeed, to obtain effective parallel
multigrid preconditioners, a tradeoff between the optimality and the cost of building and
applying the smoothers and the coarse-space corrections must be achieved. Effective
parallel preconditioners require algorithmic scalability to be coupled with implementation
scalability, i.e., a computational cost per iteration which remains (almost) constant as
the number of parallel processors increases.
+ HREF="node29.html#Briggs2000">3,23,21] for details.)
MLD2P4 uses a pure algebraic approach, based on the smoothed
aggregation algorithm [2,25],
for building the sequence of coarse matrices and transfer operators,
starting from the original one.
A decoupled version of this algorithm is implemented, where the smoothed
aggregation is applied locally to each submatrix [24].
A brief description of the AMG preconditioners implemented in MLD2P4 is given in
Sections 4.1-4.3. For further details the reader
is referred to [4,5,7,8].
We note that optimal multigrid preconditioners do not necessarily correspond
to minimum execution times in a parallel setting. Indeed, to obtain effective parallel
multigrid preconditioners, a tradeoff between the optimality and the cost of building and
applying the smoothers and the coarse-space corrections must be achieved. Effective
parallel preconditioners require algorithmic scalability to be coupled with implementation
scalability, i.e., a computational cost per iteration which remains (almost) constant as
the number of parallel processors increases.
Subsections
@@ -150,29 +151,91 @@ P^k \in \mathbb{R}^{n_k \times n_{k+1}}, \quad
R^k \in \mathbb{R}^{n_{k+1}\
ALT="\begin{displaymath}
P^k \in \mathbb{R}^{n_k \times n_{k+1}}, \quad
R^k \in \mathbb{R}^{n_{k+1}\times n_k};
\end{displaymath}">
-
-
+
the matrix is computed by using the previous operators according
to the Galerkin approach, i.e.,
+
+
+
+
+
+
+
+
In the current implementation of MLD2P4 we have
A smoother with iteration matrix is set up at each level , and a solver
is set up at the coarsest level, so that they are ready for application
(for example, setting up a solver based on the factorization means computing
and storing the and factors). The construction of the hierarchy of AMG components
described so far corresponds to the so-called build phase of the preconditioner.
+
+
+
Figure 1:
+Application phase of a V-cycle preconditioner.
+
+
+
+
+
+
+
+
The components produced in the build phase may be combined in several ways
to obtain different multilevel preconditioners;
this is done in the application phase, i.e., in the computation of a vector
of type , where denotes the preconditioner, usually within an iteration
of a Krylov solver [20]. An example of such a combination, known as
V-cycle, is given in Figure 1. In this case, a single iteration
of the same smoother is used before and after the the recursive call to the V-cycle (i.e.,
in the pre-smoothing and post-smoothing phases); however, different choices can be
performed. Other cycles can be defined; in MLD2P4, we implemented the standard V-cycle
and W-cycle [3], and a version of the K-cycle described
in [19].
-
-
-
-
- Next:Getting Started
- Up: Next: Smoothed Aggregation
+ Up:Multigrid Background
- Previous: Previous: Multigrid Background
- Contents
diff --git a/docs/html/node13.html b/docs/html/node13.html
index 2af33d3d..f871dd6c 100644
--- a/docs/html/node13.html
+++ b/docs/html/node13.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-Getting Started
-
+Smoothed Aggregation
+
@@ -18,206 +18,314 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
+
+
+
-
-
+
-
-
- Next:Examples
- Up:userhtml
- Previous: Next: Smoothers and coarsest-level solvers
+ Up:Multigrid Background
+ Previous:AMG preconditioners
- Contents
-
+
-Getting Started
-
-
-We describe the basics for building and applying MLD2P4 one-level and multi-level
-(i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS [13].
-The following steps are required:
-
-
+Smoothed Aggregation
+
In order to define the prolongator , used to compute
the coarse-level matrix , MLD2P4 uses the smoothed aggregation
algorithm described in [2,25].
The basic idea of this algorithm is to build a coarse set of indices
by suitably grouping the indices of into disjoint
subsets (aggregates), and to define the coarse-to-fine space transfer operator
by applying a suitable smoother to a simple piecewise constant
prolongation operator, with the aim of improving the quality of the coarse-space correction.
Three main steps can be identified in the smoothed aggregation procedure:
+
-
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.
-
-
Allocate and initialize the preconditioner data structure, according to
- a preconditioner type chosen by the user. This is performed by the routine
- init, which also sets defaults for each preconditioner
- type selected by the user. The preconditioner types and the defaults associated
- with them are given in Table 1, where the strings used by
- init to identify the preconditioner types are also given.
- Note that these strings are valid also if uppercase letters are substituted by
- corresponding lowercase ones.
-
-
Modify the selected preconditioner type, by properly setting
- preconditioner parameters. This is performed by the routine set.
- This routine must be called only if the user wants to modify the default values
- of the parameters associated with the selected preconditioner type, to obtain a variant
- of that preconditioner. Examples of use of set 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-8.
+
aggregation of the indices of to obtain ;
-
Build the preconditioner for a given matrix. If the selected preconditioner
- is multi-level, then two steps must be performed, as specified next.
-
-
4.1
-
Build the aggregation hierarchy for a given matrix. This is
-performed by the routine hierarchy_build.
-
-
4.2
-
Build the preconditioner for a given matrix. This is performed
-by the routine smoothers_build.
-
-
- If the selected preconditioner is one-level, it is built in a single step,
-performed by the routine bld.
+
construction of the prolongator ;
-
Apply the preconditioner at each iteration of a Krylov solver.
- This is performed by the routine aply. When using the PSBLAS Krylov solvers,
- this step is completely transparent to the user, since aply is called
- by the PSBLAS routine implementing the Krylov solver (psb_krylov).
+
application of and to build .
-
Free the preconditioner data structure. This is performed by
- the routine free. This step is complementary to step 1 and should
- be performed when the preconditioner is no more used.
-
-
-
-All the previous routines are available as methods of the preconditioner object.
-A detailed description of them is given in Section 6.
-Examples showing the basic use of MLD2P4 are reported in Section 5.1.
-
-
-
-
-
-
-
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' or 'JACOBI'
-
Diagonal preconditioner.
- For any zero diagonal entry of the matrix to be preconditioned,
- the corresponding entry of the preconditioner is set to 1.
-
-
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'
-
V-cycle with one hybrid forward Gauss-Seidel
- (GS) sweep as pre-smoother and one hybrid backward
- GS sweep as post-smoother, basic smoothed aggregation
- as coarsening algorithm, and LU (plus triangular solve)
- as coarsest-level solver. See the default values in
- Tables 2-8
- for further details of the preconditioner.
-
+
In order to perform the coarsening step, the smoothed aggregation algorithm
described in [25] is used. In this algorithm,
each index
+ corresponds to an aggregate of ,
consisting of a suitably chosen index
+ and indices that are (usually) contained in a
strongly-coupled neighborood of , i.e.,
+
+
+
+
+
+
+
+(3)
-
+
for a given threshold
+ (see [25] for the details).
Since this algorithm has a sequential nature, a decoupled
version of it is applied, where each processor independently executes
the algorithm on the set of indices assigned to it in the initial data
distribution. This version is embarrassingly parallel, since it does not require any data
communication. On the other hand, it may produce some nonuniform aggregates
and is strongly dependent on the number of processors and on the initial partitioning
of the matrix . Nevertheless, this parallel algorithm has been chosen for
MLD2P4, since it has been shown to produce good results in practice
[5,7,24].
The prolongator is built starting from a tentative prolongator
+, defined as
+
+
+
+
+
+
+
+(4)
-
-
-
-Note that the 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. Coarsest-level solvers based on the LU factorization,
-such as those implemented in UMFPACK, MUMPS, SuperLU, and SuperLU_Dist,
-usually lead to smaller numbers of preconditioned Krylov
-iterations than inexact solvers, when the linear system comes from
-a standard discretization of basic scalar elliptic PDE problems. However,
-this does not necessarily correspond to the smallest execution time
-on parallel computers.
-
-
-
-
-Subsections
+
where is the aggregate of
corresponding to the index
+.
is obtained by applying to a smoother
+:
+
+
+
+
in order to remove nonsmooth components from the range of the prolongator,
and hence to improve the convergence properties of the multi-level
method [2,23].
A simple choice for is the damped Jacobi smoother:
+
+
+
+
+
+
+
+
where is the diagonal matrix with the same diagonal entries as ,
+ is the filtered matrix defined as
+
+
+
+
+
+
+
+(5)
+
+
and is an approximation of , where
is the spectral radius of
+ [2].
In MLD2P4 this approximation is obtained by using
+ as an estimate
of . Note that for systems coming from uniformly elliptic
problems, filtering the matrix has little or no effect, and
can be used instead of . The latter choice is the default in MLD2P4.
-
-
+
-
-
- Next:Examples
- Up:userhtml
- Previous: Next: Smoothers and coarsest-level solvers
+ Up:Multigrid Background
+ Previous:AMG preconditioners
- Contents
diff --git a/docs/html/node14.html b/docs/html/node14.html
index a5607641..71b7a474 100644
--- a/docs/html/node14.html
+++ b/docs/html/node14.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-Examples
-
+Smoothers and coarsest-level solvers
+
@@ -19,296 +19,216 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
+
-
-
+
-
-
- Next:User Interface
- Up:Getting Started
- Previous:Getting Started
- Next:Getting Started
+ Up:Multigrid Background
+ Previous:Smoothed Aggregation
+ Contents
-
+
-Examples
-
-
-The code reported in Figure 2 shows how to set and apply the default
-multi-level preconditioner available in the real double precision version
-of MLD2P4 (see Table 1). This preconditioner is chosen
-by simply specifying 'ML' as the second argument of P%init
-(a call to P%set is not needed) and is applied with the CG
-solver provided by PSBLAS (the matrix of the system to be solved is
-assumed to be positive definite). As previously observed, the modules
-psb_base_mod, mld_prec_mod and psb_krylov_mod
-must be used by the example program.
-
-
-The part of the code concerning the
-reading and assembling of the sparse matrix and the right-hand side vector, performed
-through the PSBLAS routines for sparse matrix and vector management, is not reported
-here for brevity; the statements concerning the deallocation of the PSBLAS
-data structure are neglected too.
-The complete code can be found in the example program file mld_dexample_ml.f90,
-in the directory examples/fileread of the MLD2P4 implementation (see
-Section 3.5). A sample test problem along with the relevant
-input data is available in examples/fileread/runs.
-For details on the use of the PSBLAS routines, see the PSBLAS User's
-Guide [13].
-
-
-The setup and application of the default multi-level preconditioner
-for the real single precision and the complex, single and double
-precision, versions are obtained with straightforward modifications of the previous
-example (see Section 6 for details). If these versions are installed,
-the corresponding codes are available in examples/fileread/.
-
-
-
-
-
-
Figure 2:
-setup and application of the default multi-level preconditioner (example 1).
-
-
+Smoothers and coarsest-level solvers
+
The smoothers implemented in MLD2P4 include the Jacobi and block-Jacobi methods,
a hybrid version of the forward and backward Gauss-Seidel methods, and the
additive Schwarz (AS) ones (see, e.g., [20,21]).
The hybrid Gauss-Seidel
version is considered because the original Gauss-Seidel method is inherently sequential.
At each iteration of the hybrid version, each parallel process uses the most recent values
of its own local variables and the values of the non-local variables computed at the
previous iteration, obtained by exchanging data with other processes before
the beginning of the current iteration.
In the AS methods, the index space is divided into
subsets of size , possibly
overlapping. For each we consider the restriction
operator
+
that maps a vector to the vector made of the components of
with indices in , and the prolongation operator
+. These operators are then used to build
+, which is the restriction of to the index
space .
The classical AS preconditioner is defined as
+
-
-
-
- use psb_base_mod
- use mld_prec_mod
- use psb_krylov_mod
-... ...
-!
-! sparse matrix
- type(psb_dspmat_type) :: A
-! sparse matrix descriptor
- type(psb_desc_type) :: desc_A
-! preconditioner
- type(mld_dprec_type) :: P
-! right-hand side and solution vectors
- type(psb_d_vect_type) :: b, x
-... ...
-!
-! initialize the parallel environment
- call psb_init(ictxt)
- call psb_info(ictxt,iam,np)
-... ...
-!
-! read and assemble the spd matrix A and the right-hand side b
-! using PSBLAS routines for sparse matrix / vector management
-... ...
-!
-! initialize the default multi-level preconditioner, i.e. V-cycle
-! with basic smoothed aggregation, 1 hybrid forward/backward
-! GS sweep as pre/post-smoother and UMFPACK as coarsest-level
-! solver
- call P%init('ML',info)
-!
-! build the preconditioner
- call P%hierarchy_build(A,desc_A,info)
- call P%smoothers_build(A,desc_A,info)
+
-!
-! set the solver parameters and the initial guess
- ... ...
-!
-! solve Ax=b with preconditioned CG
- call psb_krylov('CG',A,P,b,x,tol,desc_A,info)
- ... ...
-!
-! deallocate the preconditioner
- call P%free(info)
-!
-! deallocate other data structures
- ... ...
-!
-! exit the parallel environment
- call psb_exit(ictxt)
- stop
-
-
-
-
-
-
-
+
-
-
-Different versions of the multi-level preconditioner can be obtained by changing
-the default values of the preconditioner parameters. The code reported in
-Figure 3 shows how to set a V-cycle preconditioner
-which applies 1 block-Jacobi sweep as pre- and post-smoother,
-and solves the coarsest-level system with 8 block-Jacobi sweeps.
-Note that the ILU(0) factorization (plus triangular solve) is used as
-local solver for the block-Jacobi sweeps, since this is the default associated
-with block-Jacobi and set by P%init.
-Furthermore, specifying block-Jacobi as coarsest-level
-solver implies that the coarsest-level matrix is distributed
-among the processes.
-Figure 4 shows how to set a W-cycle preconditioner which
-applies 2 hybrid Gauss-Seidel sweeps as pre- and post-smoother,
-and solves the coarsest-level system with the multifrontal LU factorization
-implemented in MUMPS. It is specified that the coarsest-level
-matrix is distributed, since MUMPS can be used on both
-replicated and distributed matrices, and by default
-it is used on replicated ones. The code fragments shown in Figures 3 and 4 are
-included in the example program file mld_dexample_ml.f90 too.
-
-
-Finally, Figure 5 shows the setup of a one-level
-additive Schwarz preconditioner, i.e., RAS with overlap 2.
-Note also that a Krylov method different from CG must be used to solve
-the preconditioned system, since the preconditione in nonsymmetric.
-The corresponding example program is available in the file
-mld_dexample_1lev.f90.
-
-
-For all the previous preconditioners, example programs where the sparse matrix and
-the right-hand side are generated by discretizing a PDE with Dirichlet
-boundary conditions are also available in the directory examples/pdegen.
-
-
-
-
-
-
Figure 3:
-setup of a multi-level preconditioner
-
-
-
-
-
-... ...
-! build a V-cycle preconditioner with 1 block-Jacobi sweep (with
-! ILU(0) on the blocks) as pre- and post-smoother, and 8 block-Jacobi
-! sweeps (with ILU(0) on the blocks) as coarsest-level solver
- call P%init('ML',info)
- call_P%set('SMOOTHER_TYPE','BJAC',info)
- call P%set('COARSE_SOLVE','BJAC',info)
- call P%set('COARSE_SWEEPS',8,info)
- call P%hierarchy_build(A,desc_A,info)
- call P%smoothers_build(A,desc_A,info)
-... ...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Figure 4:
-setup of a multi-level preconditioner
-
-
-
-
-
-... ...
-! build a W-cycle preconditioner with 2 hybrid Gauss-Seidel sweeps
-! as pre- and post-smoother, a distributed coarsest
-! matrix, and MUMPS as coarsest-level solver
- call P%init('ML',info)
- call P%set('ML_CYCLE','WCYCLE',info)
- call P%set('SMOOTHER_TYPE','FBGS',info)
- call P%set('SMOOTHER_SWEEPS',2,info)
- call P%set('COARSE_SOLVE','MUMPS',info)
- call P%set('COARSE_MAT','DIST',info)
- call P%hierarchy_build(A,desc_A,info)
- call P%smoothers_build(A,desc_A,info)
-... ...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Figure 5:
-setup of a one-level Schwarz preconditioner.
-
-
-
-
-
-... ...
-! set RAS with overlap 2 and ILU(0) on the local blocks
- call P%init('AS',info)
- call P%set('SUB_OVR',2,info)
- call P%bld(A,desc_A,info)
-... ...
-! solve Ax=b with preconditioned BiCGSTAB
- call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
-
-
-
-
-
-
-
-
-
-
-
+
+
where is supposed to be nonsingular. We observe that an approximate
inverse of is usually considered instead of .
The setup of during the multilevel build phase
involves
+
+
+
the definition of the index subspaces and of the corresponding
operators (and );
+
+
the computation of the submatrices ;
+
+
the computation of their inverses (usually approximated
through some form of incomplete factorization).
+
+
The computation of
+, with
+, during the
multilevel application phase, requires
+
+
+
the restriction of to the subspaces
+,
i.e.
+;
+
+
the computation of the vectors
+;
+
+
the prolongation and the sum of the previous vectors,
i.e.
+.
+
+
Variants of the classical AS method, which use modifications of the
restriction and prolongation operators, are also implemented in MLD2P4.
Among them, the Restricted AS (RAS) preconditioner usually
outperforms the classical AS preconditioner in terms of convergence
rate and of computation and communication time on parallel distributed-memory
computers, and is therefore the most widely used among the AS
preconditioners [6].
Direct solvers based on sparse LU factorizations, implemented in the
third-party libraries reported in Section 3.2, can be applied
as coarsest-level solvers by MLD2P4. Native inexact solvers based on
incomplete LU factorizations, as well as Jacobi, hybrid (forward) Gauss-Seidel,
and block Jacobi preconditioners are also available. Direct solvers usually
lead to more effective preconditioners in terms of algorithmic scalability;
however, this does not guarantee parallel efficiency.
+
-
-
+
-
-
- Next:User Interface
- Up:Getting Started
- Previous:Getting Started
- Next:Getting Started
+ Up:Multigrid Background
+ Previous:Smoothed Aggregation
+ Contents
diff --git a/docs/html/node15.html b/docs/html/node15.html
index a364c90b..ca695c21 100644
--- a/docs/html/node15.html
+++ b/docs/html/node15.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-User Interface
-
+Getting Started
+
@@ -18,96 +18,173 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
+
+
-
-
-
-
- Next:Subroutine init
- Up: Next: Examples
+ Up:userhtml
- Previous:Examples
- Previous:Smoothers and coarsest-level solvers
+ Contents
-
+
-User Interface
+Getting Started
-The basic user interface of MLD2P4 consists of eight routines. The six
-routines init, set,
-hierarchy_build, smoothers_build,
-bld, and apply encapsulate all the
-functionalities for the setup and the application of any multi-level and one-level
-preconditioner implemented in the package.
-The routine free deallocates the preconditioner data structure, while
-descr prints a description of the preconditioner setup by the user.
-
-
-All the routines are available as methods of the preconditioner object.
-For each routine, the same user interface is overloaded with
-respect to the real/ complex case and the single/double precision;
-arguments with appropriate data types must be passed to the routine,
-i.e.,
+We describe the basics for building and applying MLD2P4 one-level and multi-level
+(i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS [13].
+The following steps are required:
-
-
the sparse matrix data structure, containing the matrix to be
- preconditioned, must be of type psb_xspmat_type
- with x = s for real single precision, x = d
- for real double precision, x = c for complex single precision,
- x = z for complex double precision;
+
+
+
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.
+
+
Allocate and initialize the preconditioner data structure, according to
+ a preconditioner type chosen by the user. This is performed by the routine
+ init, which also sets defaults for each preconditioner
+ type selected by the user. The preconditioner types and the defaults associated
+ with them are given in Table 1, where the strings used by
+ init to identify the preconditioner types are also given.
+ Note that these strings are valid also if uppercase letters are substituted by
+ corresponding lowercase ones.
-
the preconditioner data structure must be of type
- mld_xprec_type, with x =
- s, d, c, z, according to the sparse
- matrix data structure;
+
Modify the selected preconditioner type, by properly setting
+ preconditioner parameters. This is performed by the routine set.
+ This routine must be called only if the user wants to modify the default values
+ of the parameters associated with the selected preconditioner type, to obtain a variant
+ of that preconditioner. Examples of use of set 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-8.
-
the arrays containing the vectors and involved in
- the preconditioner application must be of type
- psb_xvect_type with x =
- s, d, c, z, in a manner completely
- analogous to the sparse matrix type;
+
Build the preconditioner for a given matrix. If the selected preconditioner
+ is multi-level, then two steps must be performed, as specified next.
+
+
4.1
+
Build the aggregation hierarchy for a given matrix. This is
+performed by the routine hierarchy_build.
+
+
4.2
+
Build the preconditioner for a given matrix. This is performed
+by the routine smoothers_build.
+
+
+ If the selected preconditioner is one-level, it is built in a single step,
+performed by the routine bld.
-
real parameters defining the preconditioner must be declared
- according to the precision of the sparse matrix and preconditioner
- data structures (see Section 6.2).
+
Apply the preconditioner at each iteration of a Krylov solver.
+ This is performed by the routine aply. When using the PSBLAS Krylov solvers,
+ this step is completely transparent to the user, since aply is called
+ by the PSBLAS routine implementing the Krylov solver (psb_krylov).
-
-A description of each routine is given in the remainder of this section.
+
Free the preconditioner data structure. This is performed by
+ the routine free. This step is complementary to step 1 and should
+ be performed when the preconditioner is no more used.
+
+
+
+All the previous routines are available as methods of the preconditioner object.
+A detailed description of them is given in Section 6.
+Examples showing the basic use of MLD2P4 are reported in Section 5.1.
+
+
+
+
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' or 'JACOBI'
+
Diagonal preconditioner.
+ For any zero diagonal entry of the matrix to be preconditioned,
+ the corresponding entry of the preconditioner is set to 1.
+
+
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'
+
V-cycle with one hybrid forward Gauss-Seidel
+ (GS) sweep as pre-smoother and one hybrid backward
+ GS sweep as post-smoother, basic smoothed aggregation
+ as coarsening algorithm, and LU (plus triangular solve)
+ as coarsest-level solver. See the default values in
+ Tables 2-8
+ for further details of the preconditioner.
+
+
+
+
+
+
+
+Note that the 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. Coarsest-level solvers based on the LU factorization,
+such as those implemented in UMFPACK, MUMPS, SuperLU, and SuperLU_Dist,
+usually lead to smaller numbers of preconditioned Krylov
+iterations than inexact solvers, when the linear system comes from
+a standard discretization of basic scalar elliptic PDE problems. However,
+this does not necessarily correspond to the smallest execution time
+on parallel computers.
@@ -115,46 +192,32 @@ A description of each routine is given in the remainder of this section.
Subsections
+The code reported in Figure 2 shows how to set and apply the default
+multi-level preconditioner available in the real double precision version
+of MLD2P4 (see Table 1). This preconditioner is chosen
+by simply specifying 'ML' as the second argument of P%init
+(a call to P%set is not needed) and is applied with the CG
+solver provided by PSBLAS (the matrix of the system to be solved is
+assumed to be positive definite). As previously observed, the modules
+psb_base_mod, mld_prec_mod and psb_krylov_mod
+must be used by the example program.
+
+
+The part of the code concerning the
+reading and assembling of the sparse matrix and the right-hand side vector, performed
+through the PSBLAS routines for sparse matrix and vector management, is not reported
+here for brevity; the statements concerning the deallocation of the PSBLAS
+data structure are neglected too.
+The complete code can be found in the example program file mld_dexample_ml.f90,
+in the directory examples/fileread of the MLD2P4 implementation (see
+Section 3.5). A sample test problem along with the relevant
+input data is available in examples/fileread/runs.
+For details on the use of the PSBLAS routines, see the PSBLAS User's
+Guide [13].
+
-
-This routine allocates and initializes the preconditioner
-p, according to the preconditioner type chosen by the user.
+The setup and application of the default multi-level preconditioner
+for the real single precision and the complex, single and double
+precision, versions are obtained with straightforward modifications of the previous
+example (see Section 6 for details). If these versions are installed,
+the corresponding codes are available in examples/fileread/.
-Arguments
-
+
+
+
+
Figure 2:
+setup and application of the default multi-level preconditioner (example 1).
+
+
+
+
+
+
+ use psb_base_mod
+ use mld_prec_mod
+ use psb_krylov_mod
+... ...
+!
+! sparse matrix
+ type(psb_dspmat_type) :: A
+! sparse matrix descriptor
+ type(psb_desc_type) :: desc_A
+! preconditioner
+ type(mld_dprec_type) :: P
+! right-hand side and solution vectors
+ type(psb_d_vect_type) :: b, x
+... ...
+!
+! initialize the parallel environment
+ call psb_init(ictxt)
+ call psb_info(ictxt,iam,np)
+... ...
+!
+! read and assemble the spd matrix A and the right-hand side b
+! using PSBLAS routines for sparse matrix / vector management
+... ...
+!
+! initialize the default multi-level preconditioner, i.e. V-cycle
+! with basic smoothed aggregation, 1 hybrid forward/backward
+! GS sweep as pre/post-smoother and UMFPACK as coarsest-level
+! solver
+ call P%init('ML',info)
+!
+! build the preconditioner
+ call P%hierarchy_build(A,desc_A,info)
+ call P%smoothers_build(A,desc_A,info)
+
+!
+! set the solver parameters and the initial guess
+ ... ...
+!
+! solve Ax=b with preconditioned CG
+ call psb_krylov('CG',A,P,b,x,tol,desc_A,info)
+ ... ...
+!
+! deallocate the preconditioner
+ call P%free(info)
+!
+! deallocate other data structures
+ ... ...
+!
+! exit the parallel environment
+ call psb_exit(ictxt)
+ stop
+
+
+
+
+
+
+
+
-
-
ptype
-
character(len=*), intent(in).
-
-
-
-
The type of preconditioner. Its values are specified
- in Table 1.
-
-
-
-
Note that the strings are case insensitive.
-
-
-info
-
integer, intent(out).
-
-
-
-
Error code. If no error, 0 is returned. See Section 8 for details.
-
-
+Different versions of the multi-level preconditioner can be obtained by changing
+the default values of the preconditioner parameters. The code reported in
+Figure 3 shows how to set a V-cycle preconditioner
+which applies 1 block-Jacobi sweep as pre- and post-smoother,
+and solves the coarsest-level system with 8 block-Jacobi sweeps.
+Note that the ILU(0) factorization (plus triangular solve) is used as
+local solver for the block-Jacobi sweeps, since this is the default associated
+with block-Jacobi and set by P%init.
+Furthermore, specifying block-Jacobi as coarsest-level
+solver implies that the coarsest-level matrix is distributed
+among the processes.
+Figure 4 shows how to set a W-cycle preconditioner which
+applies 2 hybrid Gauss-Seidel sweeps as pre- and post-smoother,
+and solves the coarsest-level system with the multifrontal LU factorization
+implemented in MUMPS. It is specified that the coarsest-level
+matrix is distributed, since MUMPS can be used on both
+replicated and distributed matrices, and by default
+it is used on replicated ones. The code fragments shown in Figures 3 and 4 are
+included in the example program file mld_dexample_ml.f90 too.
+
-For compatibility with the previous versions of MLD2P4, this routine can be also invoked
-as follows:
+Finally, Figure 5 shows the setup of a one-level
+additive Schwarz preconditioner, i.e., RAS with overlap 2.
+Note also that a Krylov method different from CG must be used to solve
+the preconditioned system, since the preconditione in nonsymmetric.
+The corresponding example program is available in the file
+mld_dexample_1lev.f90.
+For all the previous preconditioners, example programs where the sparse matrix and
+the right-hand side are generated by discretizing a PDE with Dirichlet
+boundary conditions are also available in the directory examples/pdegen.
+
+
+
+
+
+
Figure 3:
+setup of a multi-level preconditioner
+
+
+
+
+
+... ...
+! build a V-cycle preconditioner with 1 block-Jacobi sweep (with
+! ILU(0) on the blocks) as pre- and post-smoother, and 8 block-Jacobi
+! sweeps (with ILU(0) on the blocks) as coarsest-level solver
+ call P%init('ML',info)
+ call_P%set('SMOOTHER_TYPE','BJAC',info)
+ call P%set('COARSE_SOLVE','BJAC',info)
+ call P%set('COARSE_SWEEPS',8,info)
+ call P%hierarchy_build(A,desc_A,info)
+ call P%smoothers_build(A,desc_A,info)
+... ...
+
+
+
+
+
+
+
+
+
+
-
call mld_precinit(p,ptype,info)
-
+
+
+
Figure 4:
+setup of a multi-level preconditioner
+
+
+
+
+
+... ...
+! build a W-cycle preconditioner with 2 hybrid Gauss-Seidel sweeps
+! as pre- and post-smoother, a distributed coarsest
+! matrix, and MUMPS as coarsest-level solver
+ call P%init('ML',info)
+ call P%set('ML_CYCLE','WCYCLE',info)
+ call P%set('SMOOTHER_TYPE','FBGS',info)
+ call P%set('SMOOTHER_SWEEPS',2,info)
+ call P%set('COARSE_SOLVE','MUMPS',info)
+ call P%set('COARSE_MAT','DIST',info)
+ call P%hierarchy_build(A,desc_A,info)
+ call P%smoothers_build(A,desc_A,info)
+... ...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Figure 5:
+setup of a one-level Schwarz preconditioner.
+
+
+
+
+
+... ...
+! set RAS with overlap 2 and ILU(0) on the local blocks
+ call P%init('AS',info)
+ call P%set('SUB_OVR',2,info)
+ call P%bld(A,desc_A,info)
+... ...
+! solve Ax=b with preconditioned BiCGSTAB
+ call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
+
-
-This routine sets the parameters defining the preconditioner p. More
-precisely, the parameter identified by what is assigned the value
-contained in val.
-
-
-Arguments
-
-
-
-
-
what
-
character(len=*).
-
-
-
-
The parameter to be set. It can be specified through its name;
- the string is case-insensitive. See
- Tables 2-8.
The value of the parameter to be set. The list of allowed
- values and the corresponding data types is given in
- Tables 2-8.
- When the value is of type character(len=*),
- it is also treated as case insensitive.
-
-
-info
-
integer, intent(out).
-
-
-
-
Error code. If no error, 0 is returned. See Section 8
- for details.
-
-
-ilev
-
integer, optional, intent(in).
-
-
-
-
For the multi-level preconditioner, the level at which the
- preconditioner parameter has to be set.
- The levels are numbered in increasing
- order starting from the finest one, i.e., level 1 is the finest level.
- If ilev is not present, the parameter identified by what
- is set at all the appropriate levels (see
- Tables 2-8).
-
-
-ilmax
-
integer, optional, intent(in).
-
-
-
-
For the multi-level preconditioner, when both
- ilev and ilmax are present, the settings
- are applied at all levels ilev:ilmax. When
- ilev is present but ilmax is not, then
- the default is ilmax=ilev.
- The levels are numbered in increasing
- order starting from the finest one, i.e., level 1 is the finest level.
-
-
-pos
-
charater(len=*), optional, intent(in).
-
-
-
-
Whether the other arguments apply only to the pre-smoother ('PRE')
- or to the post-smoother ('POST'). If pos is not present,
- the other arguments are applied to both smoothers.
- If the preconditioner is one-level or the parameter identified by what
- does not concern the smoothers, pos is ignored.
-
-
-
-
-For compatibility with the previous versions of MLD2P4, this routine can be also invoked
-as follows:
+User Interface
+
+
+The basic user interface of MLD2P4 consists of eight routines. The six
+routines init, set,
+hierarchy_build, smoothers_build,
+bld, and apply encapsulate all the
+functionalities for the setup and the application of any multi-level and one-level
+preconditioner implemented in the package.
+The routine free deallocates the preconditioner data structure, while
+descr prints a description of the preconditioner setup by the user.
-
-
call mld_precset(p,what,val,info)
-
-
-
-However, in this case the optional arguments ilev, ilmax, and pos
-cannot be used.
-
-
-A variety of preconditioners can be obtained
-by a suitable setting of the preconditioner parameters. These parameters
-can be logically divided into four groups, i.e., parameters defining
+All the routines are available as methods of the preconditioner object.
+For each routine, the same user interface is overloaded with
+respect to the real/ complex case and the single/double precision;
+arguments with appropriate data types must be passed to the routine,
+i.e.,
-
-
the type of multi-level cycle and how many cycles must be applied;
+
+
the sparse matrix data structure, containing the matrix to be
+ preconditioned, must be of type psb_xspmat_type
+ with x = s for real single precision, x = d
+ for real double precision, x = c for complex single precision,
+ x = z for complex double precision;
-
the aggregation algorithm;
+
the preconditioner data structure must be of type
+ mld_xprec_type, with x =
+ s, d, c, z, according to the sparse
+ matrix data structure;
-
the coarse-space correction at the coarsest level (for multi-level
- preconditioners only);
+
the arrays containing the vectors and involved in
+ the preconditioner application must be of type
+ psb_xvect_type with x =
+ s, d, c, z, in a manner completely
+ analogous to the sparse matrix type;
-
the smoother of the multi-level preconditioners, or the one-level
- preconditioner.
-
-
+
real parameters defining the preconditioner must be declared
+ according to the precision of the sparse matrix and preconditioner
+ data structures (see Section 6.2).
-
-A list of the parameters that can be set, along with their allowed and
-default values, is given in Tables 2-8.
-For a description of the meaning of the parameters, please
-refer also to Section 4.
-
-
-Remark 2. A smoother is usually obtained by combining two objects:
-a smoother (SMOOTHER_TYPE) and a local solver (SUB_SOLVE),
-as specified in Tables 7-8.
-For example, the block-Jacobi smoother using
-ILU(0) on the blocks is obtained by combining the block-Jacobi smoother
-object with the ILU(0) solver object. Similarly,
-the hybrid Gauss-Seidel smoother (see Note in Table 7)
-is obtained by combining the block-Jacobi smoother object with a single sweep
-of the Gauss-Seidel solver object, while the point-Jacobi smoother is the
-result of combining the block-Jacobi smoother object with a single sweep
-of the pointwise-Jacobi solver object. However, for simplicity, shortcuts are
-provided to set point-Jacobi, hybrid (forward) Gauss-Seidel, and
-hybrid backward Gauss-Seidel, i.e., the previous smoothers can be defined
-by setting only SMOOTHER_TYPE to appropriate values (see
-Tables 7), i.e., without setting
-SUB_SOLVE too.
-
-
-The smoother and solver objects are arranged in a
-hierarchical manner. When specifying a smoother object, its parameters,
-including the local solver, are set to their default values, and when a solver
-object is specified, its defaults are also set, overriding in both
-cases any previous settings even if explicitly specified. Therefore if
-the user sets a smoother, and wishes to use a solver
-different from the default one, the call to set the solver must come
-after the call to set the smoother.
-
-
-Similar considerations apply to the point-Jacobi, Gauss-Seidel and block-Jacobi
-coarsest-level solvers, and shortcuts are available
-in this case too (see Table 5).
-
-
-Remark 3. In general, a coarsest-level solver cannot be used with
-both the replicated and distributed coarsest-matrix layout;
-therefore, setting the solver after the layout may change the layout.
-Similarly, setting the layout after the solver may change the solver.
-
-
-More precisely, UMFPACK and SuperLU require the coarsest-level
-matrix to be replicated, while SuperLU_Dist requires it to be distributed.
-In these cases, setting the coarsest-level solver implies that
-the layout is redefined according to the solver, ovverriding any
-previous settings. MUMPS, point-Jacobi,
-hybrid Gauss-Seidel and block-Jacobi can be applied to
-replicated and distributed matrices, thus their choice
-does not modify any previously specified layout.
-It is worth noting that, when the matrix is replicated,
-the point-Jacobi, hybrid Gauss-Seidel and block-Jacobi solvers
-reduce to the corresponding local solver objects (see Remark 2).
-For the point-Jacobi and Gauss-Seidel solvers, these objects
-correspond to a single point-Jacobi sweep and a single
-Gauss-Seidel sweep, respectively, which are very poor solvers.
+
+A description of each routine is given in the remainder of this section.
-On the other hand, the distributed layout can be used with any solver
-but UMFPACK and SuperLU; therefore, if any of these two solvers has already
-been selected, the coarsest-level solver is changed to block-Jacobi,
-with the previously chosen solver applied to the local blocks.
-Likewise, the replicated layout can be used with any solver but SuperLu_Dist;
-therefore, if SuperLu_Dist has been previously set, the coarsest-level
-solver is changed to the default sequential solver.
-
-
-
-
-
-
-
Table 2:
-Parameters defining the multi-level cycle and the number of cycles to
-be applied.
-
-Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and
- is included for compatibility with previous versions of MLD2P4.
-
-
'OUTER_SWEEPS'
-
integer
-
Any integer
-
-number
-
1
-
Number of multi-level cycles.
-
-
-
-
-
-
-
-
-
-
-
-
-
Table 3:
-Parameters defining the aggregation algorithm.
-
-
-
-
-
what
-
DATA TYPE
-
val
-
DEFAULT
-
COMMENTS
-
-
'MIN_COARSE_SIZE'
-
integer
-
Any number
-
-
-
-, where is the dimension
- of the matrix at the finest level
-
Coarse size threshold. The aggregation stops
- if the global number of variables of the
- computed coarsest matrix
- is lower than or equal to this threshold
- (see Note).
-
-
'MIN_CR_RATIO'
-
real
-
Any number
-
-
-
1.5
-
Minimum coarsening ratio. The aggregation stops
- if the ratio between the matrix dimensions
- at two consecutive levels is lower than or equal to this
- threshold (see Note).
-
-
'MAX_LEVS'
-
integer
-
Any integer
-
-number
-
20
-
Maximum number of levels. The aggregation stops
- if the number of levels reaches this value (see Note).
-
-
'PAR_AGGR'
-
character(len=*)
-
'DEC', 'SYMDEC'
-
'DEC'
-
Parallel aggregation algorithm.
-
-Currently, only the
- decoupled aggregation (DEC) is available; the
- SYMDEC option applies decoupled
- aggregation to the sparsity pattern
- of .
-
-
'AGGR_TYPE'
-
character(len=*)
-
'VMB'
-
'VMB'
-
Type of aggregation algorithm: currently, the scalar aggregation
- algorithm by Vanek, Mandel and Brezina is implemented
- [25].
-
-
'AGGR_PROL'
-
character(len=*)
-
'SMOOTHED', 'UNSMOOTHED'
-
'SMOOTHED'
-
Prolongator used by the aggregation algorithm: smoothed or unsmoothed
- (i.e., tentative prolongator).
-
-
Note. The aggregation algorithm stops when
-at least one of the following criteria is met:
-the coarse size threshold, the
-
-
maximum coarsening ratio, or the maximum number
-of levels is reached. Therefore, the actual number of levels may be
-
-
smaller than the specified maximum number
-of levels.
-
-
-
-
-
-
-
-
-
-
-
-
-
Table 4:
-Parameters defining the aggregation algorithm (continued).
-
-
-
-
-
what
-
DATA TYPE
-
val
-
DEFAULT
-
COMMENTS
-
-
'AGGR_ORD'
-
character(len=*)
-
'NATURAL'
-
-'DEGREE'
-
'NATURAL'
-
Initial ordering of indices for the aggregation
- algorithm: either natural ordering or sorted by
- descending degrees of the nodes in the
- matrix graph.
-
-
'AGGR_THRESH'
-
real(kind_parameter)
-
Any real
-
-number
-
0.05
-
The threshold in the aggregation algorithm,
- see (3) in Section 4.2.
- See also the note at the bottom of this table.
-
-
'AGGR_FILTER'
-
character(len=*)
-
'FILTER'
-
-'NOFILTER'
-
'NOFILTER'
-
Matrix used in computing the smoothed
- prolongator: filtered or unfiltered (see (4) in Section 4.2).
-
-
Note. Different thresholds at different levels, such as
-those used in [25, Section 5.1], can be easily set by
-invoking the rou-
-
-
tine set with
-the parameter ilev.
-
-
-
-
-
-
-
-
-
-
-
-
Table 5:
-Parameters defining the coarse-space correction at the coarsest
-level.
-
-
-
-
what
-
DATA TYPE
-
val
-
DEFAULT
-
COMMENTS
-
-
'COARSE_MAT'
-
character(len=*)
-
'DIST'
-
-'REPL'
-
'REPL'
-
Coarsest matrix layout: distributed among the processes or
- replicated on each of them.
-
-
'COARSE_SOLVE'
-
character(len=*)
-
'MUMPS'
-
-'UMF'
-
-'SLU'
-
-'SLUDIST'
-
-'JACOBI'
-
-'GS'
-
-'BJAC'
-
See Note.
-
Solver used at the coarsest level: sequential
- LU from MUMPS, UMFPACK, or SuperLU
- (plus triangular solve);
- distributed LU from MUMPS or SuperLU_Dist
- (plus triangular solve);
- point-Jacobi, hybrid Gauss-Seidel or block-Jacobi.
-
-Note that UMF and SLU require the coarsest
- matrix to be replicated, SLUDIST, JACOBI,
- GS and BJAC require it to be
- distributed, MUMPS can be used with either
- a replicated or a distributed matrix. When any of the previous
- solvers is specified, the matrix layout is set to a default
- value
- which allows the use
- value UMFPACK and SuperLU_Dist
- are available only in double precision.
-
-
'COARSE_SUBSOLVE'
-
character(len=*)
-
'ILU'
-
-'ILUT'
-
-'MILU'
-
-'MUMPS'
-
-'SLU'
-
-'UMF'
-
See Note.
-
Solver for the diagonal blocks of the coarse matrix,
- in case the block Jacobi solver
- is chosen as coarsest-level solver: ILU(), ILU(),
- MILU(), LU from MUMPS, SuperLU or UMFPACK
- (plus triangular solve).
- Note that UMFPACK and SuperLU_Dist
- are available only in double precision.
-
-
Note. Defaults for COARSE_SOLVE and
-COARSE_SUBSOLVE are chosen in the following order:
-
-
single precision version - MUMPS if installed,
- then SLU if installed,
- ILU otherwise;
-
-
double precision version - UMF if installed,
- then MUMPS if installed, then SLU if
- installed, ILU otherwise.
-
-
-
-
-
-
-
-
-
-
-
-
-
Table 6:
-Parameters defining the coarse-space correction at the coarsest
-level (continued).
-
-
-
-
what
-
DATA TYPE
-
val
-
DEFAULT
-
COMMENTS
-
-
'COARSE_SWEEPS'
-
integer
-
Any integer
-
-number
-
10
-
Number of sweeps when JACOBI, GS or BJAC
- is chosen as coarsest-level solver.
-
-
'COARSE_FILLIN'
-
integer
-
Any integer
-
-number
-
0
-
Fill-in level of the ILU factorizations.
-
-
'COARSE_ILUTHRS'
-
real(kind_parameter)
-
Any real
-
-number
-
0
-
Drop tolerance in the ILU() factorization.
-
-
-
-
-
-
-
-
-
-
-
Table 7:
-Parameters defining the smoother or the details of the one-level preconditioner.
-
-
-
-
-
-what
-
DATA TYPE
-
val
-
DEFAULT
-
-COMMENTS
-
-
'SMOOTHER_TYPE'
-
character(len=*)
-
-
'JACOBI'
-
-'GS'
-
-'BGS'
-
-'BJAC'
-
-
-'AS'
-
-
'FBGS'
-
-
Type of smoother used in the multi-level preconditioner:
- point-Jacobi, hybrid (forward) Gauss-Seidel,
- hybrid backward Gauss-Seidel, block-Jacobi, and
- Additive Schwarz.
-
-It is ignored by one-level preconditioners.
-
-
'SUB_SOLVE'
-
character(len=*)
-
-
'JACOBI'
-
-'GS'
-
-'BGS'
-
-'ILU'
-
-'ILUT'
-
-'MILU'
-
-'MUMPS'
-
-'SLU'
-
-'UMF'
-
-
GS and BGS for pre- and post-smoothers
- of multi-level preconditioners, respectively
-
-ILU for block-Jacobi and Additive Schwarz
- one-level preconditioners
-
-
The local solver to be used with the smoother or one-level
- preconditioner (see Remark 2, page 24): point-Jacobi,
- hybrid (forward) Gauss-Seidel, hybrid backward
- Gauss-Seidel, ILU(), ILU(), MILU(),
- LU from MUMPS, SuperLU or UMFPACK
- (plus triangular solve). See Note for details on hybrid
- Gauss-Seidel.
-
-
'SMOOTHER_SWEEPS'
-
integer
-
-
Any integer
-
-number
-
-
1
-
-
Number of sweeps of the smoother or one-level preconditioner.
- In the multi-level case, no pre-smother or
- post-smoother is used if this parameter is set to 0
- together with pos='PRE' or pos='POST,
- respectively.
-
-
'SUB_OVR'
-
integer
-
-
Any integer
-
-number
-
-
1
-
-
Number of overlap layers, for Additive Schwarz only.
-
-
-
-
-
-
-
-
-
-
-
-
Table 8:
-Parameters defining the smoother or the details of the one-level preconditioner
-(continued).
-
-
-
-
-what
-
DATA TYPE
-
val
-
DEFAULT
-
-COMMENTS
-
-
'SUB_RESTR'
-
character(len=*)
-
-
'HALO'
-
-'NONE'
-
-
'HALO'
-
-
Type of restriction operator, for Additive Schwarz only:
- HALO for taking into account the overlap, NONE
- for neglecting it.
-
-Note that HALO must be chosen for
- the classical Addditive Schwarz smoother and its RAS variant.
-
-
'SUB_PROL'
-
character(len=*)
-
-
'SUM'
-
-'NONE'
-
-
'NONE'
-
-
Type of prolongation operator, for Additive Schwarz only:
- SUM for adding the contributions from the overlap, NONE
- for neglecting them.
-
-Note that SUM must be chosen for the classical Additive
- Schwarz smoother, and NONE for its RAS variant.
-
-
'SUB_FILLIN'
-
integer
-
-
Any integer
-
-number
-
-
0
-
-
Fill-in level of the incomplete LU factorizations.
-This routine builds the one-level preconditioner p according to the requirements
-made by the user through the routines init and set
-(see Sections 6.4 and 6.5 for multi-level preconditioners).
+This routine allocates and initializes the preconditioner
+p, according to the preconditioner type chosen by the user.
Arguments
@@ -71,34 +70,25 @@ made by the user through the routines init and set
-
-a
-
type(psb_xspmat_type), intent(in).
+
ptype
+
character(len=*), intent(in).
-
The sparse matrix structure containing the local part of the
- matrix to be preconditioned. Note that x must be chosen according
- to the real/complex, single/double precision version of MLD2P4 under use.
- See the PSBLAS User's Guide for details [13].
-
-
-desc_a
-
type(psb_desc_type), intent(in).
+
The type of preconditioner. Its values are specified
+ in Table 1.
-
The communication descriptor of a. See the PSBLAS User's Guide for
- details [13].
+
Note that the strings are case insensitive.
-
info
+
+info
integer, intent(out).
-
Error code. If no error, 0 is returned. See Section 8 for details.
+
Error code. If no error, 0 is returned. See Section 8 for details.
@@ -107,37 +97,33 @@ as follows:
-
call mld_precbld(p,what,val,info)
+
call mld_precinit(p,ptype,info)
-
-In this case, the routine can be used to build multi-level preconditioners too.
-
-
-This routine builds the hierarchy of matrices and restriction/prolongation
-operators for the multi-level preconditioner p, according to the requirements
-made by the user through the routines init and set.
+This routine sets the parameters defining the preconditioner p. More
+precisely, the parameter identified by what is assigned the value
+contained in val.
Arguments
@@ -71,62 +71,835 @@ made by the user through the routines init and set.
-
-a
-
type(psb_xspmat_type), intent(in).
+
what
+
character(len=*).
-
The sparse matrix structure containing the local part of the
- matrix to be preconditioned. Note that x must be chosen according
- to the real/complex,
-single/double precision version of MLD2P4 under use.
- See the PSBLAS User's Guide for details [13].
+
The parameter to be set. It can be specified through its name;
+ the string is case-insensitive. See
+ Tables 2-8.
The communication descriptor of a. See the PSBLAS User's Guide for
- details [13].
+
The value of the parameter to be set. The list of allowed
+ values and the corresponding data types is given in
+ Tables 2-8.
+ When the value is of type character(len=*),
+ it is also treated as case insensitive.
-
info
+
+info
integer, intent(out).
-
Error code. If no error, 0 is returned. See Section 8 for details.
+
Error code. If no error, 0 is returned. See Section 8
+ for details.
+
+
+ilev
+
integer, optional, intent(in).
+
+
+
+
For the multi-level preconditioner, the level at which the
+ preconditioner parameter has to be set.
+ The levels are numbered in increasing
+ order starting from the finest one, i.e., level 1 is the finest level.
+ If ilev is not present, the parameter identified by what
+ is set at all the appropriate levels (see
+ Tables 2-8).
+
+
+ilmax
+
integer, optional, intent(in).
+
+
+
+
For the multi-level preconditioner, when both
+ ilev and ilmax are present, the settings
+ are applied at all levels ilev:ilmax. When
+ ilev is present but ilmax is not, then
+ the default is ilmax=ilev.
+ The levels are numbered in increasing
+ order starting from the finest one, i.e., level 1 is the finest level.
+
+
+pos
+
charater(len=*), optional, intent(in).
+
+
+
+
Whether the other arguments apply only to the pre-smoother ('PRE')
+ or to the post-smoother ('POST'). If pos is not present,
+ the other arguments are applied to both smoothers.
+ If the preconditioner is one-level or the parameter identified by what
+ does not concern the smoothers, pos is ignored.
+
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked
+as follows:
+
+
+
+
call mld_precset(p,what,val,info)
+
+
+
+However, in this case the optional arguments ilev, ilmax, and pos
+cannot be used.
+
+
+A variety of preconditioners can be obtained
+by a suitable setting of the preconditioner parameters. These parameters
+can be logically divided into four groups, i.e., parameters defining
+
+
+
the type of multi-level cycle and how many cycles must be applied;
+
+
the aggregation algorithm;
+
+
the coarse-space correction at the coarsest level (for multi-level
+ preconditioners only);
+
+
the smoother of the multi-level preconditioners, or the one-level
+ preconditioner.
+
+
+
+
+A list of the parameters that can be set, along with their allowed and
+default values, is given in Tables 2-8.
+For a description of the meaning of the parameters, please
+refer also to Section 4.
+
+
+Remark 2. A smoother is usually obtained by combining two objects:
+a smoother (SMOOTHER_TYPE) and a local solver (SUB_SOLVE),
+as specified in Tables 7-8.
+For example, the block-Jacobi smoother using
+ILU(0) on the blocks is obtained by combining the block-Jacobi smoother
+object with the ILU(0) solver object. Similarly,
+the hybrid Gauss-Seidel smoother (see Note in Table 7)
+is obtained by combining the block-Jacobi smoother object with a single sweep
+of the Gauss-Seidel solver object, while the point-Jacobi smoother is the
+result of combining the block-Jacobi smoother object with a single sweep
+of the pointwise-Jacobi solver object. However, for simplicity, shortcuts are
+provided to set point-Jacobi, hybrid (forward) Gauss-Seidel, and
+hybrid backward Gauss-Seidel, i.e., the previous smoothers can be defined
+by setting only SMOOTHER_TYPE to appropriate values (see
+Tables 7), i.e., without setting
+SUB_SOLVE too.
+
+
+The smoother and solver objects are arranged in a
+hierarchical manner. When specifying a smoother object, its parameters,
+including the local solver, are set to their default values, and when a solver
+object is specified, its defaults are also set, overriding in both
+cases any previous settings even if explicitly specified. Therefore if
+the user sets a smoother, and wishes to use a solver
+different from the default one, the call to set the solver must come
+after the call to set the smoother.
+
+
+Similar considerations apply to the point-Jacobi, Gauss-Seidel and block-Jacobi
+coarsest-level solvers, and shortcuts are available
+in this case too (see Table 5).
+
+
+Remark 3. In general, a coarsest-level solver cannot be used with
+both the replicated and distributed coarsest-matrix layout;
+therefore, setting the solver after the layout may change the layout.
+Similarly, setting the layout after the solver may change the solver.
+
+
+More precisely, UMFPACK and SuperLU require the coarsest-level
+matrix to be replicated, while SuperLU_Dist requires it to be distributed.
+In these cases, setting the coarsest-level solver implies that
+the layout is redefined according to the solver, ovverriding any
+previous settings. MUMPS, point-Jacobi,
+hybrid Gauss-Seidel and block-Jacobi can be applied to
+replicated and distributed matrices, thus their choice
+does not modify any previously specified layout.
+It is worth noting that, when the matrix is replicated,
+the point-Jacobi, hybrid Gauss-Seidel and block-Jacobi solvers
+reduce to the corresponding local solver objects (see Remark 2).
+For the point-Jacobi and Gauss-Seidel solvers, these objects
+correspond to a single point-Jacobi sweep and a single
+Gauss-Seidel sweep, respectively, which are very poor solvers.
+
+
+On the other hand, the distributed layout can be used with any solver
+but UMFPACK and SuperLU; therefore, if any of these two solvers has already
+been selected, the coarsest-level solver is changed to block-Jacobi,
+with the previously chosen solver applied to the local blocks.
+Likewise, the replicated layout can be used with any solver but SuperLu_Dist;
+therefore, if SuperLu_Dist has been previously set, the coarsest-level
+solver is changed to the default sequential solver.
+
+
+
+
+
+
+
Table 2:
+Parameters defining the multi-level cycle and the number of cycles to
+be applied.
+
+Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and
+ is included for compatibility with previous versions of MLD2P4.
+
+
'OUTER_SWEEPS'
+
integer
+
Any integer
+
+number
+
1
+
Number of multi-level cycles.
+
+
+
+
+
+
+
+
+
+
+
+
+
Table 3:
+Parameters defining the aggregation algorithm.
+
+
+
+
+
what
+
DATA TYPE
+
val
+
DEFAULT
+
COMMENTS
+
+
'MIN_COARSE_SIZE'
+
integer
+
Any number
+
+
+
+, where is the dimension
+ of the matrix at the finest level
+
Coarse size threshold. The aggregation stops
+ if the global number of variables of the
+ computed coarsest matrix
+ is lower than or equal to this threshold
+ (see Note).
+
+
'MIN_CR_RATIO'
+
real
+
Any number
+
+
+
1.5
+
Minimum coarsening ratio. The aggregation stops
+ if the ratio between the matrix dimensions
+ at two consecutive levels is lower than or equal to this
+ threshold (see Note).
+
+
'MAX_LEVS'
+
integer
+
Any integer
+
+number
+
20
+
Maximum number of levels. The aggregation stops
+ if the number of levels reaches this value (see Note).
+
+
'PAR_AGGR'
+
character(len=*)
+
'DEC', 'SYMDEC'
+
'DEC'
+
Parallel aggregation algorithm.
+
+Currently, only the
+ decoupled aggregation (DEC) is available; the
+ SYMDEC option applies decoupled
+ aggregation to the sparsity pattern
+ of .
+
+
'AGGR_TYPE'
+
character(len=*)
+
'VMB'
+
'VMB'
+
Type of aggregation algorithm: currently, the scalar aggregation
+ algorithm by Vanek, Mandel and Brezina is implemented
+ [25].
+
+
'AGGR_PROL'
+
character(len=*)
+
'SMOOTHED', 'UNSMOOTHED'
+
'SMOOTHED'
+
Prolongator used by the aggregation algorithm: smoothed or unsmoothed
+ (i.e., tentative prolongator).
+
+
Note. The aggregation algorithm stops when
+at least one of the following criteria is met:
+the coarse size threshold, the
+
+
maximum coarsening ratio, or the maximum number
+of levels is reached. Therefore, the actual number of levels may be
+
+
smaller than the specified maximum number
+of levels.
+
+
+
+
+
+
+
+
+
+
+
+
+
Table 4:
+Parameters defining the aggregation algorithm (continued).
+
+
+
+
+
what
+
DATA TYPE
+
val
+
DEFAULT
+
COMMENTS
+
+
'AGGR_ORD'
+
character(len=*)
+
'NATURAL'
+
+'DEGREE'
+
'NATURAL'
+
Initial ordering of indices for the aggregation
+ algorithm: either natural ordering or sorted by
+ descending degrees of the nodes in the
+ matrix graph.
+
+
'AGGR_THRESH'
+
real(kind_parameter)
+
Any real
+
+number
+
0.05
+
The threshold in the aggregation algorithm,
+ see (3) in Section 4.2.
+ See also the note at the bottom of this table.
+
+
'AGGR_FILTER'
+
character(len=*)
+
'FILTER'
+
+'NOFILTER'
+
'NOFILTER'
+
Matrix used in computing the smoothed
+ prolongator: filtered or unfiltered (see (5) in Section 4.2).
+
+
Note. Different thresholds at different levels, such as
+those used in [25, Section 5.1], can be easily set by
+invoking the rou-
+
+
tine set with
+the parameter ilev.
+
+
+
+
+
+
+
+
+
+
+
+
+
Table 5:
+Parameters defining the coarse-space correction at the coarsest
+level.
+
+
+
+
what
+
DATA TYPE
+
val
+
DEFAULT
+
COMMENTS
+
+
'COARSE_MAT'
+
character(len=*)
+
'DIST'
+
+'REPL'
+
'REPL'
+
Coarsest matrix layout: distributed among the processes or
+ replicated on each of them.
+
+
'COARSE_SOLVE'
+
character(len=*)
+
'MUMPS'
+
+'UMF'
+
+'SLU'
+
+'SLUDIST'
+
+'JACOBI'
+
+'GS'
+
+'BJAC'
+
See Note.
+
Solver used at the coarsest level: sequential
+ LU from MUMPS, UMFPACK, or SuperLU
+ (plus triangular solve);
+ distributed LU from MUMPS or SuperLU_Dist
+ (plus triangular solve);
+ point-Jacobi, hybrid Gauss-Seidel or block-Jacobi.
+
+Note that UMF and SLU require the coarsest
+ matrix to be replicated, SLUDIST, JACOBI,
+ GS and BJAC require it to be
+ distributed, MUMPS can be used with either
+ a replicated or a distributed matrix. When any of the previous
+ solvers is specified, the matrix layout is set to a default
+ value
+ which allows the use
+ value UMFPACK and SuperLU_Dist
+ are available only in double precision.
+
+
'COARSE_SUBSOLVE'
+
character(len=*)
+
'ILU'
+
+'ILUT'
+
+'MILU'
+
+'MUMPS'
+
+'SLU'
+
+'UMF'
+
See Note.
+
Solver for the diagonal blocks of the coarse matrix,
+ in case the block Jacobi solver
+ is chosen as coarsest-level solver: ILU(), ILU(),
+ MILU(), LU from MUMPS, SuperLU or UMFPACK
+ (plus triangular solve).
+ Note that UMFPACK and SuperLU_Dist
+ are available only in double precision.
+
+
Note. Defaults for COARSE_SOLVE and
+COARSE_SUBSOLVE are chosen in the following order:
+
+
single precision version - MUMPS if installed,
+ then SLU if installed,
+ ILU otherwise;
+
+
double precision version - UMF if installed,
+ then MUMPS if installed, then SLU if
+ installed, ILU otherwise.
+
+
+
+
+
+
+
+
+
+
+
+
+
Table 6:
+Parameters defining the coarse-space correction at the coarsest
+level (continued).
+
+
+
+
what
+
DATA TYPE
+
val
+
DEFAULT
+
COMMENTS
+
+
'COARSE_SWEEPS'
+
integer
+
Any integer
+
+number
+
10
+
Number of sweeps when JACOBI, GS or BJAC
+ is chosen as coarsest-level solver.
+
+
'COARSE_FILLIN'
+
integer
+
Any integer
+
+number
+
0
+
Fill-in level of the ILU factorizations.
+
+
'COARSE_ILUTHRS'
+
real(kind_parameter)
+
Any real
+
+number
+
0
+
Drop tolerance in the ILU() factorization.
+
+
+
+
+
+
+
+
+
+
+
+
+
Table 7:
+Parameters defining the smoother or the details of the one-level preconditioner.
+
+
+
+
+
+what
+
DATA TYPE
+
val
+
DEFAULT
+
+COMMENTS
+
+
'SMOOTHER_TYPE'
+
character(len=*)
+
+
'JACOBI'
+
+'GS'
+
+'BGS'
+
+'BJAC'
+
+
+'AS'
+
+
'FBGS'
+
+
Type of smoother used in the multi-level preconditioner:
+ point-Jacobi, hybrid (forward) Gauss-Seidel,
+ hybrid backward Gauss-Seidel, block-Jacobi, and
+ Additive Schwarz.
+
+It is ignored by one-level preconditioners.
+
+
'SUB_SOLVE'
+
character(len=*)
+
+
'JACOBI'
+
+'GS'
+
+'BGS'
+
+'ILU'
+
+'ILUT'
+
+'MILU'
+
+'MUMPS'
+
+'SLU'
+
+'UMF'
+
+
GS and BGS for pre- and post-smoothers
+ of multi-level preconditioners, respectively
+
+ILU for block-Jacobi and Additive Schwarz
+ one-level preconditioners
+
+
The local solver to be used with the smoother or one-level
+ preconditioner (see Remark 2, page 24): point-Jacobi,
+ hybrid (forward) Gauss-Seidel, hybrid backward
+ Gauss-Seidel, ILU(), ILU(), MILU(),
+ LU from MUMPS, SuperLU or UMFPACK
+ (plus triangular solve). See Note for details on hybrid
+ Gauss-Seidel.
+
+
'SMOOTHER_SWEEPS'
+
integer
+
+
Any integer
+
+number
+
+
1
+
+
Number of sweeps of the smoother or one-level preconditioner.
+ In the multi-level case, no pre-smother or
+ post-smoother is used if this parameter is set to 0
+ together with pos='PRE' or pos='POST,
+ respectively.
+
+
'SUB_OVR'
+
integer
+
+
Any integer
+
+number
+
+
1
+
+
Number of overlap layers, for Additive Schwarz only.
+
+
+
+
+
+
+
+
+
+
+
+
Table 8:
+Parameters defining the smoother or the details of the one-level preconditioner
+(continued).
+
+
+
+
+what
+
DATA TYPE
+
val
+
DEFAULT
+
+COMMENTS
+
+
'SUB_RESTR'
+
character(len=*)
+
+
'HALO'
+
+'NONE'
+
+
'HALO'
+
+
Type of restriction operator, for Additive Schwarz only:
+ HALO for taking into account the overlap, NONE
+ for neglecting it.
+
+Note that HALO must be chosen for
+ the classical Addditive Schwarz smoother and its RAS variant.
+
+
'SUB_PROL'
+
character(len=*)
+
+
'SUM'
+
+'NONE'
+
+
'NONE'
+
+
Type of prolongation operator, for Additive Schwarz only:
+ SUM for adding the contributions from the overlap, NONE
+ for neglecting them.
+
+Note that SUM must be chosen for the classical Additive
+ Schwarz smoother, and NONE for its RAS variant.
+
+
'SUB_FILLIN'
+
integer
+
+
Any integer
+
+number
+
+
0
+
+
Fill-in level of the incomplete LU factorizations.
diff --git a/docs/html/node20.html b/docs/html/node20.html
index 44b84b49..0f8f5af1 100644
--- a/docs/html/node20.html
+++ b/docs/html/node20.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-Subroutine smoothers_build
-
+Subroutine build
+
@@ -20,52 +20,50 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
+
-
-
+
-
-
- Next:Subroutine apply
- Up:User Interface
- Previous:Subroutine hierarchy_build
- Next:Subroutine hierarchy_build
+ Up:User Interface
+ Previous:Subroutine set
+ Contents
-
+
-Subroutine smoothers_build
+Subroutine build
-
call p%smoothers_build(a,desc_a,p,info)
+
call p%build(a,desc_a,info)
-This routine builds the smoothers and the coarsest-level solvers for the
-multi-level preconditioner p, according to the requirements made by
-the user through the routines init and set, and based on the aggregation
-hierarchy produced by a previous call to hierarchy_build
-(see Section 6.4).
+This routine builds the one-level preconditioner p according to the requirements
+made by the user through the routines init and set
+(see Sections 6.4 and 6.5 for multi-level preconditioners).
Arguments
@@ -74,7 +72,7 @@ hierarchy produced by a previous call to hierarchy_build
-a
+a
type(psb_xspmat_type), intent(in).
@@ -83,7 +81,7 @@ hierarchy produced by a previous call to hierarchy_build
matrix to be preconditioned. Note that x must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.
See the PSBLAS User's Guide for details [13].
+ HREF="node29.html#PSBLASGUIDE">13].
desc_a
@@ -93,39 +91,53 @@ hierarchy produced by a previous call to hierarchy_build
The communication descriptor of a. See the PSBLAS User's Guide for
details [13].
+ HREF="node29.html#PSBLASGUIDE">13].
info
integer, intent(out).
-
Error code. If no error, 0 is returned. See Section 8 for details.
+
Error code. If no error, 0 is returned. See Section 8 for details.
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked
+as follows:
+
+
+
+
call mld_precbld(p,what,val,info)
+
+
+
+In this case, the routine can be used to build multi-level preconditioners too.
+
+
-This routine computes
-, where is a previously built
-preconditioner, stored into p, and
-denotes the preconditioner itself or its transpose, according to
-the value of trans.
-Note that, when MLD2P4 is used with a Krylov solver from PSBLAS,
-p%apply is called within the PSBLAS routine psb_krylov
-and hence it is completely transparent to the user.
+This routine builds the hierarchy of matrices and restriction/prolongation
+operators for the multi-level preconditioner p, according to the requirements
+made by the user through the routines init and set.
Arguments
@@ -87,30 +71,18 @@ and hence it is completely transparent to the user.
-
x
-
type(kind_parameter), dimension(:), intent(in).
+
+a
+
type(psb_xspmat_type), intent(in).
-
The local part of the vector . Note that type and
- kind_parameter must be chosen according
- to the real/complex, single/double precision version of MLD2P4 under use.
-
-
-y
-
type(kind_parameter), dimension(:), intent(out).
-
-
-
-
The local part of the vector . Note that type and
- kind_parameter must be chosen according
- to the real/complex, single/double precision version of MLD2P4 under use.
+
The sparse matrix structure containing the local part of the
+ matrix to be preconditioned. Note that x must be chosen according
+ to the real/complex,
+single/double precision version of MLD2P4 under use.
+ See the PSBLAS User's Guide for details [13].
desc_a
@@ -118,97 +90,43 @@ and hence it is completely transparent to the user.
-
The communication descriptor associated to the matrix to be
- preconditioned.
+
The communication descriptor of a. See the PSBLAS User's Guide for
+ details [13].
-
-info
+
info
integer, intent(out).
-
Error code. If no error, 0 is returned. See Section 8 for details.
-
-
-trans
-
character(len=1), optional, intent(in).
-
-
-
-
If trans = 'N','n' then
-;
- if trans = 'T','t' then
-
- (transpose of ; if trans = 'C','c' then
-
- (conjugate transpose of .
Workspace. Its size should be at
- least 4 * psb_cd_get_local_cols(desc_a) (see the PSBLAS User's Guide).
- Note that type and kind_parameter must be chosen according
- to the real/complex, single/double precision version of MLD2P4 under use.
+
Error code. If no error, 0 is returned. See Section 8 for details.
-For compatibility with the previous versions of MLD2P4, this routine can be also invoked
-as follows:
-
-
-This routine deallocates the preconditioner data structure p.
+This routine builds the smoothers and the coarsest-level solvers for the
+multi-level preconditioner p, according to the requirements made by
+the user through the routines init and set, and based on the aggregation
+hierarchy produced by a previous call to hierarchy_build
+(see Section 6.4).
Arguments
@@ -69,27 +73,61 @@ This routine deallocates the preconditioner data structure p.
-
info
-
integer, intent(out).
+
+a
+
type(psb_xspmat_type), intent(in).
-
Error code. If no error, 0 is returned. See Section 8 for details.
+
The sparse matrix structure containing the local part of the
+ matrix to be preconditioned. Note that x must be chosen according
+ to the real/complex, single/double precision version of MLD2P4 under use.
+ See the PSBLAS User's Guide for details [13].
+
+
+desc_a
+
type(psb_desc_type), intent(in).
+
+
+
+
The communication descriptor of a. See the PSBLAS User's Guide for
+ details [13].
+
+
info
+
integer, intent(out).
+
+
+
+
Error code. If no error, 0 is returned. See Section 8 for details.
-For compatibility with the previous versions of MLD2P4, this routine can be also invoked
-as follows:
-
-
-This routine prints a description of the preconditioner p to the standard output or
-to a file. It must be called after hierachy_build and smoothers_build,
-or build, have been called.
+This routine computes
+, where is a previously built
+preconditioner, stored into p, and
+denotes the preconditioner itself or its transpose, according to
+the value of trans.
+Note that, when MLD2P4 is used with a Krylov solver from PSBLAS,
+p%apply is called within the PSBLAS routine psb_krylov
+and hence it is completely transparent to the user.
Arguments
@@ -70,21 +87,93 @@ or build, have been called.
-
info
+
x
+
type(kind_parameter), dimension(:), intent(in).
+
+
+
+
The local part of the vector . Note that type and
+ kind_parameter must be chosen according
+ to the real/complex, single/double precision version of MLD2P4 under use.
+
+
+y
+
type(kind_parameter), dimension(:), intent(out).
+
+
+
+
The local part of the vector . Note that type and
+ kind_parameter must be chosen according
+ to the real/complex, single/double precision version of MLD2P4 under use.
+
+
+desc_a
+
type(psb_desc_type), intent(in).
+
+
+
+
The communication descriptor associated to the matrix to be
+ preconditioned.
+
+
+info
integer, intent(out).
-
Error code. If no error, 0 is returned. See Section 8 for details.
+
Error code. If no error, 0 is returned. See Section 8 for details.
-iout
-
integer, intent(in), optional.
+trans
+
character(len=1), optional, intent(in).
-
The id of the file where the preconditioner description
- will be printed; the default is the standard output.
+
If trans = 'N','n' then
+;
+ if trans = 'T','t' then
+
+ (transpose of ; if trans = 'C','c' then
+
+ (conjugate transpose of .
Workspace. Its size should be at
+ least 4 * psb_cd_get_local_cols(desc_a) (see the PSBLAS User's Guide).
+ Note that type and kind_parameter must be chosen according
+ to the real/complex, single/double precision version of MLD2P4 under use.
-Adding new smoother and solver objects to MLD2P4
-
+Subroutine free
+
-Developers can add completely new smoother and/or solver classes
-derived from the base objects in the library (see Remark 2 in Section 6.2),
-without recompiling the library itself.
-
-
-To do so, it is necessary first to select the base type to be extended.
-In our experience, it is quite likely that the new application needs
-only the definition of a ``solver'' object, which is almost
-always acting only on the local part of the distributed matrix.
-The parallel actions required to connect the various solver objects
-are most often already provided by the block-Jacobi or the additive
-Schwarz smoothers. To define a new solver, the developer will then
-have to define its components and methods, perhaps taking one of the
-predefined solvers as a starting point, if possible.
-
-
-Once the new smoother/solver class has been developed, to use it in
-the context of the multilevel preconditioners it is necessary to:
-
-
-
declare in the application program a variable of the new type;
-
-
pass that variable as the argument to the set routine as in the
-following:
-
link the code implementing the various methods into the application executable.
-
-
-The new solver object is then dynamically included in the
-preconditioner structure, and acts as a mold to which the
-preconditioner will conform, even though the MLD2P4 library has not
-been modified to account for this new development.
-
+
+
call p%free(p,info)
+
-It is possible to define new values for the keyword WHAT in the
-set routine; if the library code does not recognize a keyword,
-it passes it down the composition hierarchy (levels containing
-smoothers containing in turn solvers), so that it can be eventually caught by
-the new solver.
+
+This routine deallocates the preconditioner data structure p.
-An example is provided in the source code distribution under the
-folder tests/newslv. In this example we are implementing a new
-incomplete factorization variant (which is simply the ILU(0)
-factorization under a new name). Because of the specifics of this case, it is
-possible to reuse the basic structure of the ILU solver, with its
-L/D/U components and the methods needed to apply the solver; only a
-few methods, such as the description and most importantly the build,
-need to be ovverridden (rewritten).
-
+Arguments
+
+
-The interfaces for the calls shown above are defined using
-
-
-
-smoother
-
class(mld_x_base_smoother_type)
-
-
-
-
The user-defined new smoother to be employed in the
- preconditioner.
-
-
-solver
-
class(mld_x_base_solver_type)
+
+
info
+
integer, intent(out).
-
+
-
The user-defined new solver to be employed in the
- preconditioner.
-
+
Error code. If no error, 0 is returned. See Section 8 for details.
-
-The other arguments are defined in the way described in
-Sec. 6.2. As an example, in the tests/newslv
-code we define a new object of type mld_d_tlu_solver_type, and
-we pass it as follows:
-
- ! sparse matrix and preconditioner
- type(psb_dspmat_type) :: a
- type(mld_dprec_type) :: prec
- type(mld_d_tlu_solver_type) :: tlusv
-
-......
- !
- ! prepare the preconditioner: an ML with defaults, but with TLU solver at
- ! intermediate levels. All other parameters are at default values.
- !
- call prec%init('ML', info)
- call prec%hierarchy_build(a,desc_a,info)
- nlv = prec%get_nlevs()
- call prec%set(tlusv, info,ilev=1,ilmax=max(1,nlv-1))
- call prec%smoothers_build(a,desc_a,info)
-
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked
+as follows:
+
+
+
+
call mld_precfree(p,info)
+
+
+
+
+
+
diff --git a/docs/html/node25.html b/docs/html/node25.html
index c88593b1..e2357c3c 100644
--- a/docs/html/node25.html
+++ b/docs/html/node25.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-Error Handling
-
+Subroutine descr
+
@@ -18,61 +18,112 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
+
-
-
+
-
-
- Next:License
- Up:userhtml
- Previous:Adding new smoother and
- Next:Adding new smoother and
+ Up:User Interface
+ Previous:Subroutine free
+ Contents
-
+
-Error Handling
-
+Subroutine descr
+
-The error handling in MLD2P4 is based on the PSBLAS (version 2) error
-handling. Error conditions are signaled via an integer argument
-info; whenever an error condition is detected, an error trace
-stack is built by the library up to the top-level, user-callable
-routine. This routine will then decide, according to the user
-preferences, whether the error should be handled by terminating the
-program or by returning the error condition to the user code, which
-will then take action, and whether
-an error message should be printed. These options may be set by using
-the PSBLAS error handling routines; for further details see the PSBLAS
-User's Guide [13].
-
+
+
call p%descr(info, [iout])
+
+This routine prints a description of the preconditioner p to the standard output or
+to a file. It must be called after hierachy_build and smoothers_build,
+or build, have been called.
+
+
+Arguments
+
+
+
+
+
info
+
integer, intent(out).
+
+
+
+
Error code. If no error, 0 is returned. See Section 8 for details.
+
+
+iout
+
integer, intent(in), optional.
+
+
+
+
The id of the file where the preconditioner description
+ will be printed; the default is the standard output.
+
+
+
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked
+as follows:
-
+
+
+
call mld_precdescr(p,info [,iout])
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Next:Adding new smoother and
+ Up:User Interface
+ Previous:Subroutine free
+ Contents
+
diff --git a/docs/html/node26.html b/docs/html/node26.html
index fa875782..c0265b99 100644
--- a/docs/html/node26.html
+++ b/docs/html/node26.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-License
-
+Adding new smoother and solver objects to MLD2P4
+
@@ -19,86 +19,167 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
+
-
-
-
-
- Next:Bibliography
- Up: Next: Error Handling
+ Up:userhtml
- Previous:Error Handling
- Previous:Subroutine descr
+ Contents
-
+
-License
+Adding new smoother and solver objects to MLD2P4
-The MLD2P4 is freely distributable under the following copyright
-terms:
-
-
- MLD2P4 version 2.1
- MultiLevel Domain Decomposition Parallel Preconditioners Package
- based on PSBLAS (Parallel Sparse BLAS version 3.4)
-
- (C) Copyright 2008, 2010, 2012, 2017
+Developers can add completely new smoother and/or solver classes
+derived from the base objects in the library (see Remark 2 in Section 6.2),
+without recompiling the library itself.
+
+
+To do so, it is necessary first to select the base type to be extended.
+In our experience, it is quite likely that the new application needs
+only the definition of a ``solver'' object, which is almost
+always acting only on the local part of the distributed matrix.
+The parallel actions required to connect the various solver objects
+are most often already provided by the block-Jacobi or the additive
+Schwarz smoothers. To define a new solver, the developer will then
+have to define its components and methods, perhaps taking one of the
+predefined solvers as a starting point, if possible.
+
+
+Once the new smoother/solver class has been developed, to use it in
+the context of the multilevel preconditioners it is necessary to:
+
+
+
declare in the application program a variable of the new type;
+
+
pass that variable as the argument to the set routine as in the
+following:
+
+call p%set(smoother,info [,ilev,ilmax,pos])
+ call p%set(solver,info [,ilev,ilmax,pos])
- Salvatore Filippone Cranfield University, Cranfield, UK
- Ambra Abdullahi Hassan University of Rome Tor Vergata, Rome, IT
- Alfredo Buttari CNRS-IRIT, Toulouse, FR
- Pasqua D'Ambra IAC-CNR, Naples, IT
- Daniela di Serafino University of Campania L. Vanvitelli, Caserta, IT
+
+
+
link the code implementing the various methods into the application executable.
+
+
+The new solver object is then dynamically included in the
+preconditioner structure, and acts as a mold to which the
+preconditioner will conform, even though the MLD2P4 library has not
+been modified to account for this new development.
+
+
+It is possible to define new values for the keyword WHAT in the
+set routine; if the library code does not recognize a keyword,
+it passes it down the composition hierarchy (levels containing
+smoothers containing in turn solvers), so that it can be eventually caught by
+the new solver.
+
+
+An example is provided in the source code distribution under the
+folder tests/newslv. In this example we are implementing a new
+incomplete factorization variant (which is simply the ILU(0)
+factorization under a new name). Because of the specifics of this case, it is
+possible to reuse the basic structure of the ILU solver, with its
+L/D/U components and the methods needed to apply the solver; only a
+few methods, such as the description and most importantly the build,
+need to be ovverridden (rewritten).
+
+
+The interfaces for the calls shown above are defined using
+
+
+
+smoother
+
class(mld_x_base_smoother_type)
+
+
+
+
The user-defined new smoother to be employed in the
+ preconditioner.
+
+
+solver
+
class(mld_x_base_solver_type)
+
+
+
+
The user-defined new solver to be employed in the
+ preconditioner.
+
+
+
+The other arguments are defined in the way described in
+Sec. 6.2. As an example, in the tests/newslv
+code we define a new object of type mld_d_tlu_solver_type, and
+we pass it as follows:
+
+ ! sparse matrix and preconditioner
+ type(psb_dspmat_type) :: a
+ type(mld_dprec_type) :: prec
+ type(mld_d_tlu_solver_type) :: tlusv
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions, and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
- 3. The name of the MLD2P4 group or the names of its contributors may
- not be used to endorse or promote products derived from this
- software without specific written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MLD2P4 GROUP OR ITS CONTRIBUTORS
- BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
+......
+ !
+ ! prepare the preconditioner: an ML with defaults, but with TLU solver at
+ ! intermediate levels. All other parameters are at default values.
+ !
+ call prec%init('ML', info)
+ call prec%hierarchy_build(a,desc_a,info)
+ nlv = prec%get_nlevs()
+ call prec%set(tlusv, info,ilev=1,ilmax=max(1,nlv-1))
+ call prec%smoothers_build(a,desc_a,info)
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+ Next:Error Handling
+ Up:userhtml
+ Previous:Subroutine descr
+ Contents
+
diff --git a/docs/html/node27.html b/docs/html/node27.html
index c6176e3f..1be7a8f9 100644
--- a/docs/html/node27.html
+++ b/docs/html/node27.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-Bibliography
-
+Error Handling
+
@@ -26,154 +26,53 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
-
- Next:About this document ...
- Up: Next: License
+ Up:userhtml
- Previous:License
- Previous:Adding new smoother and
+ Contents
-
-P. R. Amestoy, C. Ashcraft, O. Boiteau, A. Buttari, J. L'Excellent, C. Weisbecker,
-Improving multifrontal methods by means of block low-rank representations,
-SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452-A1474.
-See also http://mumps.enseeiht.fr.
-A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
-Extending PSBLAS to Build Parallel Schwarz Preconditioners,
-in J. Dongarra, K. Madsen, J. Wasniewski, editors,
-Proceedings of PARA 04 Workshop on State of the Art
-in Scientific Computing, Lecture Notes in Computer Science,
-Springer, 2005, 593-602.
-A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
-2LEV-D2P4: a package of high-performance preconditioners
-for scientific and engineering applications,
-Applicable Algebra in Engineering, Communications and Computing,
-18 (3) 2007, 223-239.
-X. C. Cai, M. Sarkis,
-A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems,
-SIAM Journal on Scientific Computing, 21 (2), 1999, 792-797.
-P. D'Ambra, S. Filippone, D. di Serafino,
-On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
-Applied Numerical Mathematics, Elsevier Science,
-57 (11-12), 2007, 1181-1196.
-T. A. Davis,
-Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
-Method with a Column Pre-ordering Strategy,
-ACM Transactions on Mathematical Software, 30, 2004, 196-199.
-(See also http://www.cise.ufl.edu/ davis/)
-J. W. Demmel, S. C. Eisenstat, J. R. Gilbert, X. S. Li, J. W. H. Liu,
-A supernodal approach to sparse partial pivoting,
-SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720-755.
-J. J. Dongarra, J. Du Croz, I. S. Duff, S. Hammarling,
-A set of Level 3 Basic Linear Algebra Subprograms,
-ACM Transactions on Mathematical Software, 16 (1) 1990, 1-17.
-J. J. Dongarra, J. Du Croz, S. Hammarling, R. J. Hanson,
-An extended set of FORTRAN Basic Linear Algebra Subprograms,
-ACM Transactions on Mathematical Software, 14 (1) 1988, 1-17.
-S. Filippone, A. Buttari,
-PSBLAS-3.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library, 2012,
-available from http://www.ce.uniroma2.it/psblas/.
-S. Filippone, A. Buttari,
-Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003.
-ACM Transactions on on Mathematical Software, 38 (4), 2012, art. 23.
-S. Filippone, M. Colajanni,
-PSBLAS: A Library for Parallel Linear Algebra
-Computation on Sparse Matrices,
-ACM Transactions on Mathematical Software, 26 (4), 2000, 527-550.
-W. Gropp, S. Huss-Lederman, A. Lumsdaine, E. Lusk, B. Nitzberg, W. Saphir, M. Snir,
-MPI: The Complete Reference. Volume 2 - The MPI-2 Extensions,
-MIT Press, 1998.
-C. L. Lawson, R. J. Hanson, D. Kincaid, F. T. Krogh,
-Basic Linear Algebra Subprograms for FORTRAN usage,
-ACM Transactions on Mathematical Software, 5 (3), 1979, 308-323.
-X. S. Li, J. W. Demmel,
-SuperLU_DIST: A Scalable Distributed-memory
-Sparse Direct Solver for Unsymmetric Linear Systems,
-ACM Transactions on Mathematical Software, 29 (2), 2003, 110-140.
-B. Smith, P. Bjorstad, W. Gropp,
-Domain Decomposition: Parallel Multilevel Methods for Elliptic
-Partial Differential Equations,
-Cambridge University Press, 1996.
-R. S. Tuminaro, C. Tong,
-Parallel Smoothed Aggregation Multigrid: Aggregation Strategies on Massively Parallel Machines, in J. Donnelley, editor, Proceedings of SuperComputing 2000, Dallas, 2000.
-P. Vanek, J. Mandel, M. Brezina,
-Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems,
-Computing, 56 (3) 1996, 179-196.
+
+
+Error Handling
+
-
+The error handling in MLD2P4 is based on the PSBLAS (version 2) error
+handling. Error conditions are signaled via an integer argument
+info; whenever an error condition is detected, an error trace
+stack is built by the library up to the top-level, user-callable
+routine. This routine will then decide, according to the user
+preferences, whether the error should be handled by terminating the
+program or by returning the error condition to the user code, which
+will then take action, and whether
+an error message should be printed. These options may be set by using
+the PSBLAS error handling routines; for further details see the PSBLAS
+User's Guide [13].
-
+
+
+
diff --git a/docs/html/node28.html b/docs/html/node28.html
index 71f542e2..58e4f069 100644
--- a/docs/html/node28.html
+++ b/docs/html/node28.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-About this document ...
-
+License
+
@@ -18,52 +18,86 @@ original version by: Nikos Drakos, CBLU, University of Leeds
+
+
-
-
+
+
-
-
- Up: Next: Bibliography
+ Up:userhtml
- Previous:Bibliography
- Previous:Error Handling
+ Contents
-The translation was initiated by Salvatore Filippone on 2017-07-24
+The MLD2P4 is freely distributable under the following copyright
+terms:
+
+
+ MLD2P4 version 2.1
+ MultiLevel Domain Decomposition Parallel Preconditioners Package
+ based on PSBLAS (Parallel Sparse BLAS version 3.4)
+
+ (C) Copyright 2008, 2010, 2012, 2017
+
+ Salvatore Filippone Cranfield University, Cranfield, UK
+ Ambra Abdullahi Hassan University of Rome Tor Vergata, Rome, IT
+ Alfredo Buttari CNRS-IRIT, Toulouse, FR
+ Pasqua D'Ambra IAC-CNR, Naples, IT
+ Daniela di Serafino University of Campania L. Vanvitelli, Caserta, IT
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions, and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ 3. The name of the MLD2P4 group or the names of its contributors may
+ not be used to endorse or promote products derived from this
+ software without specific written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MLD2P4 GROUP OR ITS CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+
+
+
diff --git a/docs/html/node29.html b/docs/html/node29.html
index f80ff24c..ab187489 100644
--- a/docs/html/node29.html
+++ b/docs/html/node29.html
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-About this document ...
-
+Bibliography
+
@@ -18,53 +18,162 @@ original version by: Nikos Drakos, CBLU, University of Leeds
+
+
-
-
+
+
-
-
- Up: Next: About this document ...
+ Up:userhtml
- Previous:Bibliography
- Previous:License
+ Contents
-
-
+
+P. R. Amestoy, C. Ashcraft, O. Boiteau, A. Buttari, J. L'Excellent, C. Weisbecker,
+Improving multifrontal methods by means of block low-rank representations,
+SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452-A1474.
+See also http://mumps.enseeiht.fr.
+A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
+Extending PSBLAS to Build Parallel Schwarz Preconditioners,
+in J. Dongarra, K. Madsen, J. Wasniewski, editors,
+Proceedings of PARA 04 Workshop on State of the Art
+in Scientific Computing, Lecture Notes in Computer Science,
+Springer, 2005, 593-602.
+A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
+2LEV-D2P4: a package of high-performance preconditioners
+for scientific and engineering applications,
+Applicable Algebra in Engineering, Communications and Computing,
+18 (3) 2007, 223-239.
+X. C. Cai, M. Sarkis,
+A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems,
+SIAM Journal on Scientific Computing, 21 (2), 1999, 792-797.
+P. D'Ambra, S. Filippone, D. di Serafino,
+On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
+Applied Numerical Mathematics, Elsevier Science,
+57 (11-12), 2007, 1181-1196.
+T. A. Davis,
+Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
+Method with a Column Pre-ordering Strategy,
+ACM Transactions on Mathematical Software, 30, 2004, 196-199.
+(See also http://www.cise.ufl.edu/ davis/)
+J. W. Demmel, S. C. Eisenstat, J. R. Gilbert, X. S. Li, J. W. H. Liu,
+A supernodal approach to sparse partial pivoting,
+SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720-755.
+J. J. Dongarra, J. Du Croz, I. S. Duff, S. Hammarling,
+A set of Level 3 Basic Linear Algebra Subprograms,
+ACM Transactions on Mathematical Software, 16 (1) 1990, 1-17.
+J. J. Dongarra, J. Du Croz, S. Hammarling, R. J. Hanson,
+An extended set of FORTRAN Basic Linear Algebra Subprograms,
+ACM Transactions on Mathematical Software, 14 (1) 1988, 1-17.
+S. Filippone, A. Buttari,
+PSBLAS-3.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library, 2012,
+available from http://www.ce.uniroma2.it/psblas/.
+S. Filippone, A. Buttari,
+Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003.
+ACM Transactions on on Mathematical Software, 38 (4), 2012, art. 23.
+S. Filippone, M. Colajanni,
+PSBLAS: A Library for Parallel Linear Algebra
+Computation on Sparse Matrices,
+ACM Transactions on Mathematical Software, 26 (4), 2000, 527-550.
+W. Gropp, S. Huss-Lederman, A. Lumsdaine, E. Lusk, B. Nitzberg, W. Saphir, M. Snir,
+MPI: The Complete Reference. Volume 2 - The MPI-2 Extensions,
+MIT Press, 1998.
+C. L. Lawson, R. J. Hanson, D. Kincaid, F. T. Krogh,
+Basic Linear Algebra Subprograms for FORTRAN usage,
+ACM Transactions on Mathematical Software, 5 (3), 1979, 308-323.
+X. S. Li, J. W. Demmel,
+SuperLU_DIST: A Scalable Distributed-memory
+Sparse Direct Solver for Unsymmetric Linear Systems,
+ACM Transactions on Mathematical Software, 29 (2), 2003, 110-140.
+B. Smith, P. Bjorstad, W. Gropp,
+Domain Decomposition: Parallel Multilevel Methods for Elliptic
+Partial Differential Equations,
+Cambridge University Press, 1996.
+R. S. Tuminaro, C. Tong,
+Parallel Smoothed Aggregation Multigrid: Aggregation Strategies on Massively Parallel Machines, in J. Donnelley, editor, Proceedings of SuperComputing 2000, Dallas, 2000.
+P. Vanek, J. Mandel, M. Brezina,
+Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems,
+Computing, 56 (3) 1996, 179-196.
+
-The translation was initiated by Salvatore Filippone on 2017-04-18
-
+
diff --git a/docs/html/node3.html b/docs/html/node3.html
index 5e5e3daf..07fff983 100644
--- a/docs/html/node3.html
+++ b/docs/html/node3.html
@@ -26,26 +26,26 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
-
- Next: Next: Code Distribution
- Up: Up: userhtml
- Previous: Previous: Contents
- Contents
@@ -59,9 +59,9 @@ General Overview
The MULTI-LEVEL DOMAIN DECOMPOSITION PARALLEL PRECONDITIONERS PACKAGE BASED ON
PSBLAS (MLD2P4) provides parallel Algebraic MultiGrid (AMG) and Domain
Decomposition preconditioners (see, e.g., [3,23,21]),
+ HREF="node29.html#Briggs2000">3,23,21]),
to be used in the iterative solution of linear systems,
@@ -95,8 +95,8 @@ multi-level cycles and smoothers widely used in multigrid methods.
The multi-level preconditioners implemented in MLD2P4 are obtained by combining
AMG cycles with smoothers and coarsest-level solvers. The V-, W-, and
K-cycles [3,19] are available, which allow to define
+ HREF="node29.html#Briggs2000">3,19] are available, which allow to define
almost all the preconditioners in the package, including the multi-level hybrid
Schwarz ones; a specific cycle is implemented to obtain multi-level additive
Schwarz preconditioners. The Jacobi, hybridforward/backward Gauss-Seidel, block-Jacobi, and additive Schwarz methods
@@ -104,8 +104,8 @@ are available as smoothers. An algebraic approach is used to generate a hierarch
coarse-level matrices and operators, without explicitly using any information on the
geometry of the original problem, e.g., the discretization of a PDE. To this end,
the smoothed aggregation technique [2,25]
+ HREF="node29.html#BREZINA_VANEK">2,25]
is applied. Either exact or approximate solvers can be used on the coarsest-level
system. Specifically, different sparse LU factorizations from external
packages, and native incomplete LU factorizations and Jacobi, hybrid Gauss-Seidel,
@@ -126,8 +126,8 @@ interface.
MLD2P4 has been designed to implement scalable and easy-to-use
multilevel preconditioners in the context of the PSBLAS (Parallel Sparse BLAS)
computational framework [15,14]. PSBLAS provides basic linear algebra
+ HREF="node29.html#psblas_00">15,14]. PSBLAS provides basic linear algebra
operators and data management facilities for distributed sparse matrices,
as well as parallel Krylov solvers which can be used with the MLD2P4 preconditioners.
The choice of PSBLAS has been mainly motivated by the need of having
@@ -150,14 +150,14 @@ few black-box routines at the upper layer allow all users to easily
build and apply any preconditioner available in MLD2P4;
facilities are also available allowing expert users to extend the set of smoothers
and solvers for building new versions of the preconditioners (see
-Section 7).
+Section 7).
We note that the user interface of MLD2P4 2.1 has been extended with respect to the
previous versions in order to separate the construction of the multi-level hierarchy from
the construction of the smoothers and solvers, and to allow for more flexibility
at each level. The software architecture described in [8] has significantly
+ HREF="node29.html#MLD2P4_TOMS">8] has significantly
evolved too, in order to fully exploit the Fortran 2003 features implemented in PSBLAS 3.
However, compatibility with previous versions has been preserved.
@@ -168,37 +168,37 @@ and installation of the package are given in Section 4,
to help the users in choosing among them. The basics for building and applying the
preconditioners with the Krylov solvers implemented in PSBLAS are reported
-in Section 5, where the Fortran codes of a few sample programs
+in Section 5, where the Fortran codes of a few sample programs
are also shown. A reference guide for the user interface routines is provided
-in Section 6. Information on the extension of the package
-through the addition of new smoothers and solvers is reported in Section 7.
+in Section 6. Information on the extension of the package
+through the addition of new smoothers and solvers is reported in Section 7.
The error handling mechanism used by the package
-is briefly described in Section 8. The copyright terms concerning the
-distribution and modification of MLD2P4 are reported in Appendix A.
+is briefly described in Section 8. The copyright terms concerning the
+distribution and modification of MLD2P4 are reported in Appendix A.
-A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
-Extending PSBLAS to Build Parallel Schwarz Preconditioners,
-in , J. Dongarra, K. Madsen, J. Wasniewski, editors,
-Proceedings of PARA 04 Workshop on State of the Art
-in Scientific Computing, Lecture Notes in Computer Science,
-Springer, 2005, 593-602.
-
A. Buttari, P. D'Ambra, D. di Serafino, S. Filippone,
-2LEV-D2P4: a package of high-performance preconditioners
-for scientific and engineering applications,
-Applicable Algebra in Engineering, Communications and Computing,
-18, 3, 2007, 223-239.
-
P. D'Ambra, S. Filippone, D. di Serafino,
-On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
-Applied Numerical Mathematics, Elsevier Science,
-57, 11-12, 2007, 1181-1196.
-
-
-X. C. Cai, M. Sarkis,
-A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems,
-SIAM Journal on Scientific Computing, 21, 2, 1999, 792-797.
-
-X. C. Cai, O. B. Widlund,
-Domain Decomposition Algorithms for Indefinite Elliptic Problems,
-SIAM Journal on Scientific and Statistical Computing, 13, 1, 1992, 243-258.
-
-J.W. Demmel, S.C. Eisenstat, J.R. Gilbert, X.S. Li and J.W.H. Liu,
-A supernodal approach to sparse partial pivoting,
-SIAM Journal on Matrix Analysis and Applications, 20, 3, 1999, 720-755.
-
-J. J. Dongarra, J. Du Croz, I. S. Duff, S. Hammarling,
-A set of Level 3 Basic Linear Algebra Subprograms,
-ACM Transactions on Mathematical Software, 16, 1990, 1-17.
-
-J. J. Dongarra, J. Du Croz, S. Hammarling, R. J. Hanson,
-An extended set of FORTRAN Basic Linear Algebra Subprograms,
-ACM Transactions on Mathematical Software, 14, 1988, 1-17.
-
-J. J. Dongarra and R. C. Whaley,
-A User's Guide to the BLACS v. 1.1,
-Lapack Working Note 94, Tech. Rep. UT-CS-95-281, University of
-Tennessee, March 1995 (updated May 1997).
-
-S. Filippone, A. Buttari,
-PSBLAS-2.3 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library,
-available from http://www.ce.uniroma2.it/psblas/.
-
-S. Filippone, M. Colajanni,
-PSBLAS: A Library for Parallel Linear Algebra
-Computation on Sparse Matrices,
-ACM Transactions on Mathematical Software, 26, 4, 2000, 527-550.
-
-W. Gropp, S. Huss-Lederman, A. Lumsdaine, E. Lusk, B. Nitzberg, W. Saphir, M. Snir,
-MPI: The Complete Reference. Volume 2 - The MPI-2 Extensions,
-MIT Press, 1998.
-
-C. L. Lawson, R. J. Hanson, D. Kincaid, F. T. Krogh,
-Basic Linear Algebra Subprograms for FORTRAN usage,
-ACM Transactions on Mathematical Software, 5, 1979, 308-323.
-
-X. S. Li, J. W. Demmel, SuperLU_DIST: A Scalable Distributed-memory
-Sparse Direct Solver for Unsymmetric Linear Systems,
-ACM Transactions on Mathematical Software, 29, 2, 2003, 110-140.
-
-M. Snir, S. Otto, S. Huss-Lederman, D. Walker, J. Dongarra,
-MPI: The Complete Reference. Volume 1 - The MPI Core, second edition,
-MIT Press, 1998.
-
-K. Stüben,
-Algebraic Multigrid (AMG): an Introduction with Applications,
-in A. Schüller, U. Trottenberg, C. Oosterlee, editors, Multigrid,
-Academic Press, 2000.
-
-P. Vanek, J. Mandel and M. Brezina,
-Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems,
-Computing, 56, 1996, 179-196.
-
-
+The translation was initiated by Salvatore Filippone on 2017-07-25
-
-Salvatore Filippone
-2008-07-23
-
+
diff --git a/docs/html/node4.html b/docs/html/node4.html
index 5b865be9..cb8f1623 100644
--- a/docs/html/node4.html
+++ b/docs/html/node4.html
@@ -26,26 +26,26 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
-
- Next: Next: Configuring and Building MLD2P4
- Up: Up: userhtml
- Previous: Previous: General Overview
- Contents
@@ -65,7 +65,7 @@ where contact points for further information can be also found.
The software is available under a modified BSD license, as specified
-in Appendix A; please note that some of the optional
+in Appendix A; please note that some of the optional
third party libraries may be licensed under a different and more
stringent license, most notably the GPL, and this should be taken into
account when treating derived works.
diff --git a/docs/html/node5.html b/docs/html/node5.html
index 87755718..7a4528fb 100644
--- a/docs/html/node5.html
+++ b/docs/html/node5.html
@@ -26,26 +26,26 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-
-
-
-
- Next: Next: Prerequisites
- Up: Up: userhtml
- Previous: Previous: Code Distribution
- Contents
@@ -89,40 +89,40 @@ optional software used by MLD2P4 is given in the next sections.
Subsections
[11,12,17] Many vendors provide optimized versions
+ HREF="node29.html#blas3">11,12,17] Many vendors provide optimized versions
of BLAS; if no vendor version is
available for a given platform, the ATLAS software
(
[16,22] A version of MPI is available on most
+ HREF="node29.html#MPI2">16
,22] A version of MPI is available on most
high-performance computing systems.
PSBLAS
[13,15] Parallel Sparse BLAS (PSBLAS) is
+ HREF="node29.html#PSBLASGUIDE">13,15] Parallel Sparse BLAS (PSBLAS) is
available from www.ce.uniroma2.it/psblas; version
3.5.0 (or later) is required. Indeed, all the prerequisites
@@ -108,26 +108,26 @@ compiler as MLD2P4.
@@ -64,7 +64,7 @@ for multi-level preconditioners may change to reflect their presence.
UMFPACK
[9]
+ HREF="node29.html#UMFPACK">9]
A sparse LU factorization package included in the SuiteSparse library, available from
faculty.cse.tamu.edu/davis/suitesparse.html;
@@ -75,7 +75,7 @@ for multi-level preconditioners may change to reflect their presence.
MUMPS
[1]
+ HREF="node29.html#MUMPS">1]
A sparse LU factorization package available from mumps.enseeiht.fr;
it provides sequential and parallel factorizations and triangular system solution
@@ -84,7 +84,7 @@ for multi-level preconditioners may change to reflect their presence.
SuperLU
[10]
+ HREF="node29.html#SUPERLU">10]
A sparse LU factorization package available from
crd.lbl.gov/~xiaoye/SuperLU/; it provides sequential
@@ -95,7 +95,7 @@ for multi-level preconditioners may change to reflect their presence.
SuperLU_Dist
[18]
+ HREF="node29.html#SUPERLUDIST">18]
A sparse LU factorization package available
from the same site as SuperLU; it provides parallel factorization and
triangular system solution for double precision real and complex data.
@@ -111,26 +111,26 @@ for multi-level preconditioners may change to reflect their presence.