diff --git a/docs/html/img10.png b/docs/html/img10.png index 5bbb7120..0411408d 100644 Binary files a/docs/html/img10.png and b/docs/html/img10.png differ diff --git a/docs/html/img11.png b/docs/html/img11.png index 7e6da656..5c710b74 100644 Binary files a/docs/html/img11.png and b/docs/html/img11.png differ diff --git a/docs/html/img12.png b/docs/html/img12.png index 4efe450d..de88a1b2 100644 Binary files a/docs/html/img12.png and b/docs/html/img12.png differ diff --git a/docs/html/img13.png b/docs/html/img13.png index fa7fb9a9..1ac411b8 100644 Binary files a/docs/html/img13.png and b/docs/html/img13.png differ diff --git a/docs/html/img14.png b/docs/html/img14.png index 20d767cb..bc6b7ac6 100644 Binary files a/docs/html/img14.png and b/docs/html/img14.png differ diff --git a/docs/html/img15.png b/docs/html/img15.png index 35049964..f55eaaee 100644 Binary files a/docs/html/img15.png and b/docs/html/img15.png differ diff --git a/docs/html/img16.png b/docs/html/img16.png index 65b61047..837e0808 100644 Binary files a/docs/html/img16.png and b/docs/html/img16.png differ diff --git a/docs/html/img17.png b/docs/html/img17.png index 95298ad0..a9337489 100644 Binary files a/docs/html/img17.png and b/docs/html/img17.png differ diff --git a/docs/html/img18.png b/docs/html/img18.png index c82f6505..107e05d7 100644 Binary files a/docs/html/img18.png and b/docs/html/img18.png differ diff --git a/docs/html/img19.png b/docs/html/img19.png index 0ad8c316..3936b252 100644 Binary files a/docs/html/img19.png and b/docs/html/img19.png differ diff --git a/docs/html/img20.png b/docs/html/img20.png index 2d84350d..4e67821f 100644 Binary files a/docs/html/img20.png and b/docs/html/img20.png differ diff --git a/docs/html/img21.png b/docs/html/img21.png index 5188694c..576642c2 100644 Binary files a/docs/html/img21.png and b/docs/html/img21.png differ diff --git a/docs/html/img22.png b/docs/html/img22.png index bc6b7ac6..26284a83 100644 Binary files a/docs/html/img22.png and b/docs/html/img22.png differ diff --git a/docs/html/img23.png b/docs/html/img23.png index 128353b0..28f65c01 100644 Binary files a/docs/html/img23.png and b/docs/html/img23.png differ diff --git a/docs/html/img24.png b/docs/html/img24.png index 19f13f9f..e6ddac59 100644 Binary files a/docs/html/img24.png and b/docs/html/img24.png differ diff --git a/docs/html/img25.png b/docs/html/img25.png index b403509f..3d77a9f4 100644 Binary files a/docs/html/img25.png and b/docs/html/img25.png differ diff --git a/docs/html/img26.png b/docs/html/img26.png index 716bcade..ac9d4c30 100644 Binary files a/docs/html/img26.png and b/docs/html/img26.png differ diff --git a/docs/html/img27.png b/docs/html/img27.png index 6ac2640c..925ebcf0 100644 Binary files a/docs/html/img27.png and b/docs/html/img27.png differ diff --git a/docs/html/img28.png b/docs/html/img28.png index 34b1fe8f..1265a058 100644 Binary files a/docs/html/img28.png and b/docs/html/img28.png differ diff --git a/docs/html/img29.png b/docs/html/img29.png index ca70256b..70ca59b3 100644 Binary files a/docs/html/img29.png and b/docs/html/img29.png differ diff --git a/docs/html/img30.png b/docs/html/img30.png index 922efa68..9485b3d5 100644 Binary files a/docs/html/img30.png and b/docs/html/img30.png differ diff --git a/docs/html/img31.png b/docs/html/img31.png index 0103648e..dbec189b 100644 Binary files a/docs/html/img31.png and b/docs/html/img31.png differ diff --git a/docs/html/img32.png b/docs/html/img32.png index 5ebbdb04..429992b0 100644 Binary files a/docs/html/img32.png and b/docs/html/img32.png differ diff --git a/docs/html/img33.png b/docs/html/img33.png index cce6da93..f93f9c2c 100644 Binary files a/docs/html/img33.png and b/docs/html/img33.png differ diff --git a/docs/html/img34.png b/docs/html/img34.png index b0d94c65..87c32133 100644 Binary files a/docs/html/img34.png and b/docs/html/img34.png differ diff --git a/docs/html/img35.png b/docs/html/img35.png index 9485b3d5..38f6623b 100644 Binary files a/docs/html/img35.png and b/docs/html/img35.png differ diff --git a/docs/html/img36.png b/docs/html/img36.png index dbec189b..9272159c 100644 Binary files a/docs/html/img36.png and b/docs/html/img36.png differ diff --git a/docs/html/img37.png b/docs/html/img37.png index 41241bb5..81a5b301 100644 Binary files a/docs/html/img37.png and b/docs/html/img37.png differ diff --git a/docs/html/img38.png b/docs/html/img38.png index 70e444a1..fa33fb71 100644 Binary files a/docs/html/img38.png and b/docs/html/img38.png differ diff --git a/docs/html/img39.png b/docs/html/img39.png index 128353b0..9379b219 100644 Binary files a/docs/html/img39.png and b/docs/html/img39.png differ diff --git a/docs/html/img4.png b/docs/html/img4.png index d8a3c7e4..fddc68e2 100644 Binary files a/docs/html/img4.png and b/docs/html/img4.png differ diff --git a/docs/html/img40.png b/docs/html/img40.png index 95a25705..bbd27ccc 100644 Binary files a/docs/html/img40.png and b/docs/html/img40.png differ diff --git a/docs/html/img41.png b/docs/html/img41.png index 487184fb..9cb3e942 100644 Binary files a/docs/html/img41.png and b/docs/html/img41.png differ diff --git a/docs/html/img42.png b/docs/html/img42.png index 62de8047..63b88f84 100644 Binary files a/docs/html/img42.png and b/docs/html/img42.png differ diff --git a/docs/html/img5.png b/docs/html/img5.png index 5ee3ef30..ea6bc428 100644 Binary files a/docs/html/img5.png and b/docs/html/img5.png differ diff --git a/docs/html/img6.png b/docs/html/img6.png index a9bfb385..54d05606 100644 Binary files a/docs/html/img6.png and b/docs/html/img6.png differ diff --git a/docs/html/img7.png b/docs/html/img7.png index 27d0856f..cc2fbfd8 100644 Binary files a/docs/html/img7.png and b/docs/html/img7.png differ diff --git a/docs/html/img8.png b/docs/html/img8.png index a0964077..23c8fdcd 100644 Binary files a/docs/html/img8.png and b/docs/html/img8.png differ diff --git a/docs/html/img9.png b/docs/html/img9.png index 7b1e80b1..455ad05a 100644 Binary files a/docs/html/img9.png and b/docs/html/img9.png differ diff --git a/docs/html/index.html b/docs/html/index.html index 3655cc3c..3dcd3433 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -23,18 +23,18 @@ original version by: Nikos Drakos, CBLU, University of Leeds
--MLD2P4 has been designed to provide scalable and easy-to-use preconditioners in the -context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms) +MLD2P4 has been designed to provide scalable and easy-to-use preconditioners +in the context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms) computational framework and can be used in conjuction with the Krylov solvers -available in this framework. MLD2P4 enables the user to easily specify different features -of an algebraic multi-level preconditioner, thus allowing to search +available in this framework. MLD2P4 enables the user to easily specify different +features of an algebraic multi-level preconditioner, thus allowing to search for the ``best'' preconditioner for the problem at hand.
@@ -92,26 +90,26 @@ the user interface of MLD2P4.
fileread
and
runs
subdirectories, to experiment with the full range of preconditioners
- implemented in the library.
+ implemented in the package.
fileread
directories contain sample programs that read
sparse matrices from files, according to the Matrix Market or the
-Harwell-Boeing storage format; the pdegen
instead generate
-matrices in full parallel mode from the discretization of a sample PDE.
+Harwell-Boeing storage format; the pdegen
programs generate
+matrices in full parallel mode from the discretization of a sample partial
+differential equation.
-Domain Decomposition (DD) preconditioners, coupled with Krylov iterative -solvers, are widely used in the parallel solution of large and sparse linear systems. -These preconditioners are based on the divide and conquer technique: the matrix -to be preconditioned is divided into submatrices, a ``local'' linear system -involving each submatrix is (approximately) solved, and the local solutions are used -to build a preconditioner for the whole original matrix. This process -often corresponds to dividing a physical domain associated to the original matrix -into subdomains, e.g. in a PDE discretization, to (approximately) solving the -subproblems corresponding to the subdomains and to building an approximate -solution of the original problem from the local solutions -[6,7,23]. - -
-Additive Schwarz preconditioners are DD preconditioners using overlapping -submatrices, i.e. with some common rows, to couple the local information -related to the submatrices (see, e.g., [23]). -The main motivation for choosing Additive Schwarz preconditioners is their -intrinsic parallelism. A drawback of these -preconditioners is that the number of iterations of the preconditioned solvers -generally grows with the number of submatrices. This may be a serious limitation -on parallel computers, since the number of submatrices usually matches the number -of available processors. Optimal convergence rates, i.e. iteration numbers -independent of the number of submatrices, can be obtained by correcting the -preconditioner through a suitable approximation of the original linear system -in a coarse space, which globally couples the information related to the single -submatrices. - -
-Two-level Schwarz preconditioners are obtained -by combining basic (one-level) Schwarz preconditioners with a coarse-level -correction. In this context, the one-level preconditioner is often -called `smoother'. Different two-level preconditioners are obtained by varying the -choice of the smoother and of the coarse-level correction, and the -way they are combined [23]. The same reasoning can be applied starting -from the coarse-level system, i.e. a coarse-space correction can be built -from this system, thus obtaining multi-level preconditioners. - -
-It is worth noting that optimal preconditioners do not necessarily correspond -to minimum execution times. Indeed, to obtain effective multi-level preconditioners -a tradeoff between optimality of convergence and the cost of building and applying -the coarse-space corrections must be achieved. The choice of the number of levels, -i.e. of the coarse-space corrections, also affects the effectiveness of the -preconditioners. One more goal is to get convergence rates as less sensitive -as possible to variations in the matrix coefficients. - -
-Two main approaches can be used to build coarse-space corrections. The geometric approach -applies coarsening strategies based on the knowledge of some physical grid associated -to the matrix and requires the user to define grid transfer operators from the fine -to the coarse levels and vice versa. This may result difficult for complex geometries; -furthermore, suitable one-level preconditioners may be required to get efficient -interplay between fine and coarse levels, e.g. when matrices with highly varying coefficients -are considered. The algebraic approach builds coarse-space corrections using only matrix -information. It performs a fully automatic coarsening and enforces the interplay between -the fine and coarse levels by suitably choosing the coarse space and the coarse-to-fine -interpolation [25]. - -
-MLD2P4 uses a pure algebraic approach for building the sequence of coarse matrices -starting from the original matrix. The algebraic approach is based on the smoothed -aggregation algorithm [1,27]. A decoupled version -of this algorithm is implemented, where the smoothed aggregation is applied locally -to each submatrix [26]. In the next two subsections we provide -a brief description of the multi-level Schwarz preconditioners and of the smoothed -aggregation technique as implemented in MLD2P4. For further details the reader -is referred to [2,3,4,8,23]. - -
-
-The Multilevel preconditioners implemented in MLD2P4 are obtained by combining -AS preconditioners with coarse-space corrections; therefore -we first provide a sketch of the AS preconditioners. - -
-Given the linear system , + +
![]() |
++(2) |
-Let be the size of
and
-
the restriction operator that maps
-a vector
onto the vector
-
-containing the components of
corresponding to the vertices in
-
. The transpose of
is a
-prolongation operator from
-
to
.
-The matrix
-
can be considered
-as a restriction of
is real, but the
results are valid for the complex case as well.
Let us assume as finest index space the set of row (column) indices of
corresponding to the set
.
-
-
-The classical one-level AS preconditioner is defined by
-
-A variant of the classical AS preconditioner that outperforms it
-in terms of convergence rate and of computation and communication
-time on parallel distributed-memory computers is the so-called Restricted AS
-(RAS) preconditioner [5,15]. It
-is obtained by zeroing the components of corresponding to the
-overlapping vertices when applying the prolongation. Therefore,
-RAS differs from classical AS by the prolongation operators,
-which are substituted by
-
,
-where
is obtained by zeroing the rows of
-corresponding to the vertices in
:
-
-As already observed, the convergence rate of the one-level Schwarz
-preconditioned iterative solvers deteriorates as the number of partitions
-of
increases [7,23]. To reduce the dependency
-of the number of iterations on the degree of parallelism we may
-introduce a global coupling among the overlapping partitions by defining
-a coarse-space approximation
of the matrix
.
-In a pure algebraic setting,
is usually built with
-the Galerkin approach. Given a set
of coarse vertices,
-with size
, and a suitable restriction operator
-
-
,
is defined as
-
-The combination of and
may be
-performed in either an additive or a multiplicative framework.
-In the former case, the two-level additive Schwarz preconditioner
-is obtained:
-
-In the multiplicative case, the combination can be
-performed by first applying the smoother and then
-the coarse-level correction operator
:
-
-As previously noted, on parallel computers the number of submatrices usually matches
-the number of available processors. When the size of the system to be preconditioned
-is very large, the use of many processors, i.e. of many small submatrices, often
-leads to a large coarse-level system, whose solution may be computationally expensive.
-On the other hand, the use of few processors often leads to local sumatrices that
-are too expensive to be processed on single processors, because of memory and/or
-computing requirements. Therefore, it seems natural to use a recursive approach,
-in which the coarse-level correction is re-applied starting from the current
-coarse-level system. The corresponding preconditioners, called multi-level
-preconditioners, can significantly reduce the computational cost of preconditioning
-with respect to the two-level case (see [23, Chapter 3]).
-Additive and hybrid multilevel preconditioners
-are obtained as direct extensions of the two-level counterparts.
-For a detailed descrition of them, the reader is
-referred to [23, Chapter 3].
-The algorithm for the application of a multi-level hybrid
-post-smoothed preconditioner to a vector
, i.e. for the
-computation of
, is reported, for
-example, in Figure 1. Here the number of levels
-is denoted by
and the levels are numbered in increasing order starting
-from the finest one, i.e. the finest level is level 1; the coarse matrix
-and the corresponding basic preconditioner at each level
are denoted by
and
-
, respectively, with
, while the related restriction operator is
-denoted by
.
-
-
-
-In order to define the restriction operator , which is used to compute
-the coarse-level matrix
, MLD2P4 uses the smoothed aggregation
-algorithm described in [1,27].
-The basic idea of this algorithm is to build a coarse set of vertices
-
by suitably grouping the vertices 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, to improve the quality of the coarse-space correction.
-
-
-Three main steps can be identified in the smoothed aggregation procedure: +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 [17]. +The following steps are required:
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.
+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.
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.
hierarchy_build
.
+smoothers_build
.
+bld
.
+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
).
+free
. This step is complementary to step 1 and should
+ be performed when the preconditioner is no more used.
-To perform the coarsening step, we have implemented the aggregation algorithm sketched
-in [4]. According to [27], a modification of
-this algorithm has been actually considered,
-in which each aggregate is made of vertices of
that are strongly coupled
-to a certain root vertex
, i.e.
-The prolongator is built starting from a tentative prolongator
-
-
, defined as
-
-
![]() |
--(2) |
+
+
-
![]() ![]() ![]() - -in order to remove oscillatory components from the range of the prolongator -and hence to improve the convergence properties of the multi-level -Schwarz method [1,25]. -A simple choice for ![]() - -where the value of ![]() ![]()
+Note that the module +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 + +
- ![]() ![]() ![]() ![]() ![]() - Next: Getting Started - Up: Multi-level Domain Decomposition Background - Previous: Multi-level Schwarz Preconditioners - Next: Examples + Up: userhtml + Previous: AMG preconditioners + Contents diff --git a/docs/html/node14.html b/docs/html/node14.html index b8317669..6ecc3856 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 --> - ![]() ![]() ![]() ![]() - Next: Examples - Up: userhtml - Previous: Smoothed Aggregation - Next: User Interface + Up: Getting Started + Previous: Getting Started + Contents -
+
+Examples
+
+
+-Getting Started -
+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 -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 [16]. -The following steps are required: - -
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 [17].
-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.
+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
-
+
+
-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. - - - - - - ![]() ![]() ![]() ![]() - Next: Subroutine hierarchy_bld - Up: User Interface - Previous: Subroutine set - Contents - + diff --git a/docs/html/node2.html b/docs/html/node2.html index 82730de5..a560c26e 100644 --- a/docs/html/node2.html +++ b/docs/html/node2.html @@ -26,21 +26,21 @@ original version by: Nikos Drakos, CBLU, University of Leeds - ![]() ![]() ![]() - Next: Next: General Overview - Up: Up: userhtml - Previous: Previous: Abstract @@ -53,70 +53,68 @@ Contents
+ HREF="node26.html">License ![]() ![]() ![]() ![]() - Next: Subroutine smoothers_bld - Up: User Interface - Previous: Subroutine bld - Next: Subroutine apply + Up: User Interface + Previous: Subroutine hierarchy_build + Contents -
+-Subroutine hierarchy_bld +Subroutine smoothers_build
-
call p%hierarchy_bld(a,desc_a,info)
+call p%smoothers_build(a,desc_a,p,info)
-This routine builds the hierarchy of matrices and restriction/prolongation
-operators for the multi-level preconditioner
Arguments
@@ -79,10 +81,9 @@ made by the user through the routines |
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.
+ to the real/complex, single/double precision version of MLD2P4 under use.
See the PSBLAS User's Guide for details [16]. |
+ HREF="node27.html#PSBLASGUIDE">17].
desc_a |
@@ -90,19 +91,18 @@ single/double precision version of MLD2P4 under use.
type(psb_desc_type), intent(in) . |
The communication descriptor of |
+ HREF="node27.html#PSBLASGUIDE">17].
a . See the PSBLAS User's Guide for
details [16].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. |
|
-
call p%smoothers_bld(a,desc_a,p,info)
+call p%apply(x,y,desc_a,info [,trans,work])
-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_bld
-(see Section 6.4).
+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
@@ -75,35 +89,122 @@ hierarchy produced by a previous call to hierarchy_bld
a |
-type(psb_ xspmat_type), intent(in) . |
+|
x |
+type( kind_parameter), dimension(:), intent(in) . |
+|
+ | The local part of the vector ![]() |
+|
y |
+type( kind_parameter), dimension(:), intent(out) . |
|
- | 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 [16]. | +The local part of the vector ![]() |
desc_a |
type(psb_desc_type), intent(in) . |
|
- | The communication descriptor of a . See the PSBLAS User's Guide for
- details [16]. |
+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. | +
trans |
+character(len=1), optional, intent(in). |
+|
+ | If trans = 'N','n' then
+![]() trans = 'T','t' then
+![]() ![]() trans = 'C','c' then
+![]() ![]() |
+|
work |
+type( kind_parameter), dimension(:), optional, target . |
+|
+ | 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. |
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked +as follows: + +
+
call mld_precaply(p,what,val,info)
+
++ +
+
call p%apply(x,y,desc_a,info [,trans,work])
+call p%free(p,info)
-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 deallocates the preconditioner data structure p
.
Arguments @@ -89,82 +71,11 @@ and hence it is completely transparent to the user.
x |
-type( kind_parameter), dimension(:), intent(in) . |
-|
- | The local part of the vector ![]() |
-|
y |
-type( kind_parameter), dimension(:), intent(out) . |
-|
- | The local part of the vector ![]() |
-|
desc_a |
-type(psb_desc_type), intent(in) . |
-|
- | The communication descriptor associated to the matrix to be - preconditioned. | -|
info |
-integer, intent(out) . |
+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
-![]() trans = 'T','t' then
-![]() ![]() trans = 'C','c' then
-![]() ![]() |
-|
work |
-type( kind_parameter), dimension(:), optional, target . |
-|
- | 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. |
call mld_precaply(p,what,val,info)
+call mld_precfree(p,info)
-
call p%free(p,info)
+call p%descr(info, [iout])
-This routine deallocates the preconditioner data structure p
.
+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
@@ -72,10 +73,17 @@ This routine deallocates the preconditioner data structure p
.
info |
-integer, intent(out) . |
+integer, intent(out) . |
+
+ | Error code. If no error, 0 is returned. See Section 8 for details. | +|
iout |
+integer, intent(in), optional . |
|
- | Error code. If no error, 0 is returned. See Section 8 for details. | +The id of the file where the preconditioner description + will be printed; the default is the standard output. |
call mld_precfree(p,info)
+call mld_precdescr(p,info [,iout])
-
call p%descr(info, [iout])
+Da ampliare e completare - SALVATORE.
-This routine prints a description of the preconditioner p
to the standard output or
-to a file. It must be called after hierachy_bld
and smoothers_bld
,
-or bld
, have been called.
+Completely new smoother and/or solver classes derived from the
+base objects in the library may be used without recompiling the
+library itself. Once the new smoother/solver class has been
+developed, the user can declare a variable of that new type in the
+application, and pass that variable to the p%set(solver,info)
+call; the new solver object is then dynamically included in the
+preconditioner structure.
-Arguments -
+ ++If the user has developed a new type of smoother and/or +solver by extending one of the base MLD2P4 types, and has declared a +variable of the new type in the main program, it is possible to pass +the new smoother/solver variable to the setup routine as follows: +
call p%set(smoother,info [,ilev, ilmax,pos])
+call p%set(solver,info [,ilev, ilmax,pos])
+
+
+
+
info |
-integer, intent(out) . |
+|
smoother |
+class(mld_x_base_smoother_type) |
|
- | Error code. If no error, 0 is returned. See Section 8 for details. | +The user-defined new smoother to be employed in the + preconditioner. |
iout |
-integer, intent(in), optional . |
+|
solver |
+class(mld_x_base_solver_type) |
|
- | The id of the file where the preconditioner description - will be printed; the default is the standard output. | +The user-defined new solver to be employed in the + preconditioner. |
-For compatibility with the previous versions of MLD2P4, this routine can be also invoked -as follows: - -
-
call mld_precdescr(p,info [,iout])
-
-- -
-
-Da ampliare e completare - SALVATORE.
-
-
-Completely new smoother and/or solver classes derived from the
-base objects in the library may be used without recompiling the
-library itself. Once the new smoother/solver class has been
-developed, the user can declare a variable of that new type in the
-application, and pass that variable to the p%set(solver,info)
-call; the new solver object is then dynamically included in the
-preconditioner structure.
+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 [17].
-
-
-
-If the user has developed a new type of smoother and/or -solver by extending one of the base MLD2P4 types, and has declared a -variable of the new type in the main program, it is possible to pass -the new smoother/solver variable to the setup routine as follows: -
call p%set(smoother,info [,ilev, ilmax,pos])
-call p%set(solver,info [,ilev, ilmax,pos])
-
-
-
-
-
-
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 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 [16].
+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. +
-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 - Ambra Abdullahi Hassan University of Rome Tor Vergata - Alfredo Buttari CNRS-IRIT, Toulouse - Pasqua D'Ambra ICAR-CNR, Naples - Daniela di Serafino Second University of Naples ++Bibliography +
+
+
+This document was generated using the +LaTeX2HTML translator Version 2012 (1.2)
-
-
-
-
-
-
-
-
+The translation was initiated by Salvatore Filippone on 2017-04-21
The MULTI-LEVEL DOMAIN DECOMPOSITION PARALLEL PRECONDITIONERS PACKAGE BASED ON
-PSBLAS (MLD2P4) provides parallel Algebraic MultiGrid (AMG) and domain decomposition
-preconditioners, designed to provide scalable and easy-to-use preconditioners
-multi-level Schwarz preconditioners [25,23],
-to be used in the iterative solutions of sparse linear systems:
+PSBLAS (MLD2P4) provides parallel Algebraic MultiGrid (AMG) and Domain
+Decomposition preconditioners (see, e.g., [2,27,25]),
+to be used in the iterative solution of linear systems,
+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 [2,23] 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 obained multi-level additive +Schwarz preconditioners. The Jacobi, hybridforward/backward Gauss-Seidel, block-Jacobi, and additive Schwarz methods +are available as smoothers. An algebraic approach is used to generate a hierarchy of +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 [1,29] +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, +and block-Jacobi solvers are available. All smoothers can be also exploited as one-level +preconditioners.
MLD2P4 is written in Fortran 2003, following an object-oriented design through the exploitation of features -such as abstract data type creation, functional overloading, and -dynamic memory management. -The parallel implementation is based on a Single Program Multiple Data +such as abstract data type creation, type extension, functional overloading, and +dynamic memory management. The parallel implementation is based on a Single Program Multiple Data (SPMD) paradigm. Single and double precision implementations of MLD2P4 are available for both the real and the complex case, which can be used through a single @@ -113,84 +124,81 @@ 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 [18,17]. -PSBLAS provides basic linear algebra +multilevel preconditioners in the context of the PSBLAS (Parallel Sparse BLAS) +computational framework [19,18]. PSBLAS provides basic linear algebra operators and data management facilities for distributed sparse matrices, -as well as parallel Krylov solvers which can be coupled with the MLD2P4 preconditioners. +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 a portable and efficient software infrastructure implementing ``de facto'' standard parallel sparse linear algebra kernels, to pursue goals such as performance, portability, modularity ed extensibility in the development of the preconditioner package. On the other hand, the implementation of MLD2P4 has led to some revisions and extentions of the original PSBLAS kernels. -The inter-process comunication required -by MLD2P4 is encapsulated into the PSBLAS routines, except few cases where -MPI [24] is explicitly called É ancora cosi???. Therefore, MLD2P4 can be run on any parallel -machine where PSBLAS and MPI implementations are available. +The inter-process comunication required by MLD2P4 is encapsulated +in the PSBLAS routines;therefore, MLD2P4 can be run on any parallel machine where PSBLAS +implementations are available.
-MLD2P4 has a layered and modular software architecture where three main layers can be identified. -The lower layer consists of the PSBLAS kernels, the middle one implements +MLD2P4 has a layered and modular software architecture where three main layers can be +identified. The lower layer consists of the PSBLAS kernels, the middle one implements the construction and application phases of the preconditioners, and the upper one provides a uniform interface to all the preconditioners. This architecture allows for different levels of use of the package: -few black-box routines at the upper layer allow non-expert users to easily -build any preconditioner available in MLD2P4 and to apply it within a PSBLAS Krylov solver; -facilities are also available that allow more expert users to extend the set of smoothers -and solvers for building new versions of preconditioners. +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).
-We note that the user interface of MLD2P4 2.1 (Perche 2.1 e non 2.0???...Ricordarsi di cambiare il configure) -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 evolved too, in order to fully exploit the -Fortran 2003 features implemented in PSBLAS 3. +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 [9] 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.
-This guide is organized as follows. General information on the distribution of the source code -is reported in Section 2, while details on the configuration -and installation of the package are given in Section 3. A short description of -the preconditioners implemented in MLD2P4 is provided -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 are also shown. A reference guide for -the upper-layer routines of MLD2P4, that are the user interface, is provided -in Section 6. 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. +This guide is organized as follows. General information on the distribution of the source +code is reported in Section 2, while details on the configuration +and installation of the package are given in Section 3. A short description +of the preconditioners implemented in MLD2P4 is provided 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 +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. +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.
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 94bdefd2..41b1e2f3 100644 --- a/docs/html/node5.html +++ b/docs/html/node5.html @@ -26,26 +26,26 @@ original version by: Nikos Drakos, CBLU, University of Leeds
-configure
+system-dependent variables; this is done by means of the configure
script. The distribution also includes the autoconf and automake
sources employed to generate the script, but usually this is not needed
to build the software.
@@ -79,15 +79,15 @@ real and complex data, in both single and double precision.
Subsections
@@ -64,73 +65,74 @@ for multi-level preconditioners may change to reflect their presence.
SuiteSparse_config/SuiteSparse_config.mk
file.
+ precision real and complex data. We tested version 4.5.4 of SuiteSparse.
+ Note that for configuring SuiteSparse you should provide the right path to the BLAS
+ and LAPACK libraries in the SuiteSparse_config/SuiteSparse_config.mk
file.
-std=c99
option to the C compiler options.
-Note that this library requires the ParMETIS
-library for parallel graph partitioning and fill-reducing matrix ordering available from
--std=c99 option to the C compiler options.
+ Note that this library requires the ParMETIS
+ library for parallel graph partitioning and fill-reducing matrix ordering, available from
+ glaros.dtc.umn.edu/gkhome/metis/parmetis/overview.
+- -
-CONTROLLARE HELP DEL CONFIGURE: Versione MLD2P4, Versione PSBLAS, Influential Environmental Variables??? - -
-To build MLD2P4 the first step is to use the configure
script
-in the main directory to generate the necessary makefile(s).
+In order to build MLD2P4, the first step is to use the configure
script
+in the main directory to generate the necessary makefile.
As a minimal example consider the following:
@@ -74,7 +71,7 @@ be specified with an absolute path).
The full set of options may be looked at by issuing the command
./configure --help
, which produces:
-`configure' configures MLD2P4 2.0 to adapt to many kinds of systems. +`configure' configures MLD2P4 2.1 to adapt to many kinds of systems. Usage: ./configure [OPTION]... [VAR=VALUE]... @@ -128,27 +125,55 @@ Fine tuning of the installation directories: --pdfdir=DIR pdf documentation [DOCDIR] --psdir=DIR ps documentation [DOCDIR] +Program names: + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM run sed PROGRAM on installed program names + Optional Features: --disable-option-checking ignore unrecognized --enable/--with options --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --disable-dependency-tracking speeds up one-time build + --enable-dependency-tracking do not reject slow dependency extractors --enable-serial Specify whether to enable a fake mpi library to run in serial mode. + --enable-long-integers Specify usage of 64 bits integers. Optional Packages: --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --with-psblas=DIR The install directory for PSBLAS, for example, - --with-psblas=/opt/packages/psblas-3.3 + --with-psblas=/opt/packages/psblas-3.5 --with-psblas-incdir=DIR Specify the directory for PSBLAS includes. --with-psblas-libdir=DIR Specify the directory for PSBLAS library. + --with-ccopt additional CCOPT flags to be added: will prepend + to CCOPT + --with-fcopt additional FCOPT flags to be added: will prepend + to FCOPT + --with-libs List additional link flags here. For example, + --with-libs=-lspecial_system_lib or + --with-libs=-L/path/to/libs + --with-clibs additional CLIBS flags to be added: will prepend + to CLIBS + --with-flibs additional FLIBS flags to be added: will prepend + to FLIBS + --with-library-path additional LIBRARYPATH flags to be added: will + prepend to LIBRARYPATH + --with-include-path additional INCLUDEPATH flags to be added: will + prepend to INCLUDEPATH + --with-module-path additional MODULE_PATH flags to be added: will + prepend to MODULE_PATH --with-extra-libs List additional link flags here. For example, --with-extra-libs=-lspecial_system_lib or --with-extra-libs=-L/path/to/libs - --with-mumps=LIBNAME Specify the libname for MUMPS. Default: "-lsmumps - -ldmumps -lcmumps -lzmumps -lmumps_common -lpord" + --with-blas=<lib> use BLAS library <lib> + --with-blasdir=<dir> search for BLAS library in <dir> + --with-lapack=<lib> use LAPACK library <lib> + --with-mumps=LIBNAME Specify the libname for MUMPS. Default: autodetect + with minimum "-lmumps_common -lpord" --with-mumpsdir=DIR Specify the directory for MUMPS library and includes. Note: you will need to add auxiliary libraries with --extra-libs; this depends on how @@ -194,24 +219,23 @@ Some influential environment variables: CFLAGS C compiler flags CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I<include dir> if you have headers in a nonstandard directory <include dir> - CPP C preprocessor MPICC MPI C compiler command - F77 Fortran 77 compiler command - FFLAGS Fortran 77 compiler flags - MPIF77 MPI Fortran 77 compiler command MPIFC MPI Fortran compiler command + CPP C preprocessor Use these variables to override the choices made by `configure' or to help it to find libraries and programs with nonstandard names/locations. Report bugs to <bugreport@mld2p4.it>.-For instance, if a user has built and installed PSBLAS 3.4 under the + +
+For instance, if a user has built and installed PSBLAS 3.5 under the
/opt
directory and is
using the SuiteSparse package (which includes UMFPACK), then MLD2P4
might be configured with:
- ./configure --with-psblas=/opt/psblas-3.4/ \ + ./configure --with-psblas=/opt/psblas-3.5/ \ --with-umfpackincdir=/usr/include/suitesparse/Once the configure script has completed execution, it will have @@ -223,7 +247,9 @@ install directory under the name
Make.inc.MLD2P4
.
To use the MUMPS solver package,
the user has to add the appropriate options to the configure script;
by default we are looking for the libraries
--ldmumps -lsmumps
-lzmumps -lzmumps -mumps_common -lpord
.
+-ldmumps -lsmumps
-lzmumps -mumps_common -lpord
.
+Pasqua, c'era due volte lzmumps. L'ho eliminato, ma poi mi e' venuto
+il dubbio che il secondo lzmumps dovesse essere modificato.
MUMPS often uses additional packages such as ScaLAPACK, ParMETIS,
SCOTCH, as well as enabling OpenMP; in such cases it is necessary to
add linker options with the --with-extra-libs
configure option.
@@ -238,26 +264,26 @@ followed (optionally) by
make install