diff --git a/docs/amg4psblas_1.0-guide.pdf b/docs/amg4psblas_1.0-guide.pdf index 8021172c..64edef08 100644 Binary files a/docs/amg4psblas_1.0-guide.pdf and b/docs/amg4psblas_1.0-guide.pdf differ diff --git a/docs/html/index.html b/docs/html/index.html index 9159b74c..bd4fb594 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -100,99 +100,80 @@ class="cmr-12">Example and test programs
4 Multigrid Background -
 4.1 AMG preconditioners -
 4.2 Smoothed Aggregation -
 4.3 Smoothers and coarsest-level solvers -
5 Getting Started
 5.1 4.1 Examples
6 5 User Interface
 6.1 5.1 Method init
 6.2 5.2 Method set
 6.3 5.3 Method hierarchy_build
 6.4 5.4 Method smoothers_build
 6.5 5.5 Method build
 6.6 5.6 Method apply
 6.7 5.7 Method free
 6.8 5.8 Method descr
 6.9 5.9 Auxiliary Methods
7 6 Adding new smoother and solver objects to AMG4PSBLAS
8 7 Error Handling
A License
References
References @@ -204,7 +185,6 @@ class="cmr-12">References - diff --git a/docs/html/userhtml.css b/docs/html/userhtml.css index 390b62d8..d4c168de 100644 --- a/docs/html/userhtml.css +++ b/docs/html/userhtml.css @@ -21,17 +21,11 @@ .cmtt-12{font-family: monospace,monospace;} .cmcsc-10x-x-120{font-size:109%;} .cmr-8{font-size:72%;} -.cmr-6{font-size:54%;} .cmmi-12{font-size:109%;font-style: italic;} .cmmi-8{font-size:72%;font-style: italic;} -.cmmi-6{font-size:54%;font-style: italic;} -.cmsy-10x-x-120{font-size:109%;} .cmsy-8{font-size:72%;} -.cmex-10x-x-120{font-size:109%;} -.msbm-10x-x-120{font-size:109%;} .cmmi-10x-x-109{font-style: italic;} .cmsy-10x-x-109{} -.cmex-10x-x-109{} .cmtt-10x-x-109{font-family: monospace,monospace;} .cmtt-10x-x-109{font-family: monospace,monospace;} .cmtt-10x-x-109{font-family: monospace,monospace;} diff --git a/docs/html/userhtml.html b/docs/html/userhtml.html index 9159b74c..bd4fb594 100644 --- a/docs/html/userhtml.html +++ b/docs/html/userhtml.html @@ -100,99 +100,80 @@ class="cmr-12">Example and test programs
4 Multigrid Background -
 4.1 AMG preconditioners -
 4.2 Smoothed Aggregation -
 4.3 Smoothers and coarsest-level solvers -
5 Getting Started
 5.1 4.1 Examples
6 5 User Interface
 6.1 5.1 Method init
 6.2 5.2 Method set
 6.3 5.3 Method hierarchy_build
 6.4 5.4 Method smoothers_build
 6.5 5.5 Method build
 6.6 5.6 Method apply
 6.7 5.7 Method free
 6.8 5.8 Method descr
 6.9 5.9 Auxiliary Methods
7 6 Adding new smoother and solver objects to AMG4PSBLAS
8 7 Error Handling
A License
References
References @@ -204,7 +185,6 @@ class="cmr-12">References - diff --git a/docs/html/userhtmlli1.html b/docs/html/userhtmlli1.html index 08d1256e..d39972dc 100644 --- a/docs/html/userhtmlli1.html +++ b/docs/html/userhtmlli1.html @@ -26,9 +26,6 @@ class="cmr-12">]

class="cmr-12">Abstract - - -

AMG4PSBLAS (Al) is a package of parallel algebraic multilevel preconditioners i PSCToolkit (Parallel Sparse Computation Toolkit) software framework. It is a progress of a software development project started in 2007, named MLD2P4, which +class="cmr-12">of a software development project started in 2007, named MLD2P4, which originally implemented a multilevel version of some domain decomposition preconditioners of + + + additive-Schwarz type and was based on a parallel decoupled version of the well known smoothed aggregation method to generate the multilevel hierarchy matrices. In the last years, within the context of the EU-H2020 EoCoE project (Energy Oriented Center of Excellence), the package was extended including +class="cmr-12">(Energy Oriented Center of Excellence), the package is being extended for new algorithms and functionalities for setup and application of new AMG +class="cmr-12">including new algorithms and functionalities to setup and apply new AMG preconditioners with the final aims of improving efficiency and scalability when tens of symmetric positive definite linear systems. Due to the significan class="cmr-12">of changes and the increase in scope, we decided to rename the package as AMG4PSBLAS. -

AMG4PSBLAS has been designed to provide scalable and easy-to-use +

AMG4PSBLAS is designed to provide scalable and easy-to-use preconditioners in preconditioners in the context of the PSBLAS (Parallel Sparse Basic Linear Algebra +class="cmr-12">the context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms) Subprograms) computational framework and can be used in conjuction with the Krylov +class="cmr-12">computational framework and can be used in conjuction with the Krylov solvers solvers available in this framework. Our package is based on a completely algebraic +class="cmr-12">available in this framework. Our package is based on a completely algebraic approach approach and users level interfaces assume that the system matrix and preconditioners +class="cmr-12">and users level interfaces assume that the system matrix and preconditioners are are represented as PSBLAS distributed sparse matrices. AMG4PSBLAS enables the +class="cmr-12">represented as PSBLAS distributed sparse matrices. AMG4PSBLAS enables the user user to easily specify different features of an algebraic multilevel preconditioner, thus +class="cmr-12">to easily specify different features of an algebraic multilevel preconditioner, thus allowing to experiment with different preconditioners for the problem and parallel computers at hand. -

The package employs object-oriented design techniques in Fortran 2003, with parallel implementation is based on a Single Program Multiple Dat class="cmr-12">paradigm; the inter-process communication is based on MPI and is managed mainly through PSBLAS. -

This guide provides a brief description of the functionalities and the user interface of AMG4PSBLAS. diff --git a/docs/html/userhtmlli2.html b/docs/html/userhtmlli2.html index d4951d95..b68e5355 100644 --- a/docs/html/userhtmlli2.html +++ b/docs/html/userhtmlli2.html @@ -74,132 +74,110 @@ class="cmr-12">Example and test programs
4 Multigrid Background +class="cmr-12">Getting Started
 4.1 AMG preconditioners -
 4.2 Smoothed Aggregation -
 4.3 Smoothers and coarsest-level solvers -
5 Getting Started -
 5.1 Examples
6 5 User Interface
 6.1 5.1 Method init
 6.2 5.2 Method set
 6.3 5.3 Method hierarchy_build
 6.4 5.4 Method smoothers_build
 6.5 5.5 Method build
 6.6 5.6 Method apply
 6.7 5.7 Method free
 6.8 5.8 Method descr
 6.9 5.9 Auxiliary Methods
  6.9.1 5.9.1 Method: dump
  6.9.2 5.9.2 Method: clone
  6.9.3 5.9.3 Method: sizeof
  6.9.4 5.9.4 Method: allocate_wrk
  6.9.5 5.9.5 Method: free_wrk
7 6 Adding new smoother and solver objects to AMG4PSBLAS
8 7 Error Handling
A License
References - - - @@ -210,9 +188,6 @@ class="cmr-12">References - - -

[

[prev] [prev-tail] [up]

References

+ id="Q1-28-46">

Transactions on Mathematical Software, 44, (2018) 39:1–39:2

[prev] [prev-tail] [23] are available, which can be combined with weighted versions of Jacobi, hybrid forward/backward Gauss-Seidel, +class="cmr-12">combined with Jacobi hybrid forward/backward Gauss-Seidel, block-Jacobi, and block-Jacobi, and additive Schwarz smoothers. Also additive Schwarz smoothers. Also ℓ1 versions of Jacobi, block-Jacobi +class="cmr-12">versions of Jacobi, block-Jacobi and Gauss-Seidel and Gauss-Seidel smoothers are available. An algebraic approach is used to generate a +class="cmr-12">smoothers are available. An algebraic approach is used to generate a hierarchy of hierarchy of coarse-level matrices and operators, without explicitly using any +class="cmr-12">coarse-level matrices and operators, without explicitly using any information information on the geometry of the original problem, e.g., the discretization of a PDE. +class="cmr-12">on the geometry of the original problem, e.g., the discretization of a PDE. To this end, two different coarsening strategies, based on aggregation, are smoothers and solvers for building new versions of the preconditi Section 76).

This guide is organized as follows. General information on the distribution of the @@ -317,35 +317,35 @@ class="cmr-12">preconditioners with the Krylov solvers implemented in PSBLAS are class="cmr-12">in Section 54, where the Fortran codes of a few sample programs are also shown. A reference guide for the user interface routines is provided in Section 65. Information on the extension of the package through the addition of new smoothers and solvers is reported in Section 76. The error handling mechanism used by the package is briefly described in Section 87. The copyright terms concerning the distribution and modification of AMG4PSBLAS are reported in Appendix A. diff --git a/docs/html/userhtmlse2.html b/docs/html/userhtmlse2.html index 9419886e..5f8b62f2 100644 --- a/docs/html/userhtmlse2.html +++ b/docs/html/userhtmlse2.html @@ -42,7 +42,7 @@ class="cmr-12">where contact points for further information can be also found.

The software is available under a modified BSD license, as specified in Appendix A; -Multigrid Background +Getting Started @@ -30,172 +30,378 @@ class="cmr-12">]

4 Multigrid Background

+class="cmr-12">Getting Started

Multigrid preconditioners, coupled with Krylov iterative solvers, are widely used in the +class="cmr-12">We describe the basics for building and applying AMG4PSBLAS one-level and 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., multilevel (i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS +[3,16]. The following steps are required: +

    +
  1. Declare the preconditioner data structure. It is a derived data type, + amg_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 AMG4PSBLAS routines, + following an object-oriented approach. +
    2. +
  2. 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 27,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. +
    3. +
  3. 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 25] for -details.) -

    MLD2P4 uses a pure algebraic approach, based on the smoothed aggregation -algorithm [2,4.1; a complete + list of all the preconditioner parameters and their allowed and default values + is provided in Section 29], for building the sequence of coarse matrices and transfer -operators, starting from the original one. A decoupled version of this algorithm +href="userhtmlse5.html#x15-140005">5, Tables 2-8. +

    4. +
  4. Build the preconditioner for a given matrix. If the selected preconditioner is + multilevel, then two steps must be performed, as specified next. +
      +
    1. Build the AMG hierarchy for a given matrix. This is performed by the + routine hierarchy_build. +
      2. +
    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. +

    5. +
  5. Apply the preconditioner at each iteration of a Krylov solver. This is performed by + the method apply. When using the PSBLAS Krylov solvers, this step is + completely transparent to the user, since apply is called by the PSBLAS routine + implementing the Krylov solver (psb_krylov). +
    6. +
  6. 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 5. Examples showing the basic use of is implemented, where the smoothed aggregation is applied locally to each -submatrix [28]. A brief description of the AMG preconditioners implemented in -MLD2P4 is given in SectionsAMG4PSBLAS are reported in Section 4.1-4.3. For further details the reader is referred to -[4, 5, 8, 9]4.1. -

We note that optimal multigrid preconditioners do not necessarily correspond to +

+ + + +

+ + + +
+

+

+ + + + + + +
type

string

default preconditioner

No preconditioner

’NONE’

Considered to use the PSBLAS Krylov solvers +with no preconditioner.

Diagonal

’DIAG’, +’JACOBI’, +’L1-JACOBI’

Diagonal preconditioner. For any zero diagonal +entry of the matrix to be preconditioned, the +corresponding entry of the preconditioner is set +to 1.

Gauss-Seidel

’GS’, +’L1-GS’

Hybrid Gauss-Seidel (forward), that is, global +block Jacobi with Gauss-Seidel as local solver.

Symmetrized Gauss-Seidel

’FBGS’, +’L1-FBGS’

Symmetrized hybrid Gauss-Seidel, that is, +forward Gauss-Seidel followed by backward +Gauss-Seidel.

Block Jacobi

’BJAC’, +’L1-BJAC’

Block-Jacobi with ILU(0) on the local blocks.

Additive Schwarz

’AS’

Additive Schwarz (AS), 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, decoupled 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.

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

Note that the module amg_prec_mod, containing the definition of the preconditioner +data type and the interfaces to the routines of AMG4PSBLAS, must be used +in any program calling such routines. The modules psb_base_mod, for the minimum execution times in a parallel setting. Indeed, to obtain effective parallel +class="cmr-12">sparse matrix and communication descriptor data types, and psb_krylov_mod, multigrid preconditioners, a tradeoff between the optimality and the cost of +class="cmr-12">for interfacing with the Krylov solvers, must be also used (see Section 4.1). +
+

Remark 1. Coarsest-level solvers based on the LU factorization, such as those building and applying the smoothers and the coarse-space corrections must be +class="cmr-12">implemented in UMFPACK, MUMPS, SuperLU, and SuperLU_Dist, usually lead to achieved. Effective parallel preconditioners require algorithmic scalability to +class="cmr-12">smaller numbers of preconditioned Krylov iterations than inexact solvers, when the be coupled with implementation scalability, i.e., a computational cost per +class="cmr-12">linear system comes from a standard discretization of basic scalar elliptic PDE iteration which remains (almost) constant as the number of parallel processors +class="cmr-12">problems. However, this does not necessarily correspond to the shortest execution time increases. -

+class="cmr-12">on parallel computers.

 4.1 AMG preconditioners -
 4.2 Smoothed Aggregation -
 4.3 Smoothers and coarsest-level solvers +class="cmr-12">Examples
- - diff --git a/docs/html/userhtmlse5.html b/docs/html/userhtmlse5.html index fb6d391b..903a5286 100644 --- a/docs/html/userhtmlse5.html +++ b/docs/html/userhtmlse5.html @@ -1,7 +1,7 @@ -Getting Started +User Interface @@ -29,385 +29,229 @@ class="cmr-12">up]

5 Getting Started

+ id="x15-140005">User Interface

We describe the basics for building and applying AMG4PSBLAS one-level and -multilevel (i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS -[16]. The following steps are required: -

    -
  1. Declare the preconditioner data structure. It is a derived data type, - amg_xprec_ type, where x may be sThe basic user interface of AMG4PBLAS consists of eight methods. The six methods +init, dset, c or z, according to the basic data +class="cmtt-12">build, hierarchy_build, smoothers_build and apply encapsulate all the +functionalities for the setup and the application of any multilevel and one-level +preconditioner implemented in the package. The method free deallocates the +preconditioner data structure, while descr prints a description of the preconditioner +setup by the user. For backward compatibility, methods are also accessible as +stand-alone subroutines. +

    For each method, 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 method, i.e., +

      +
    • the sparse matrix data structure, containing the matrix to be preconditioned, type of the sparse matrix (must be of type psb_xspmat_type with x = s = real single precision; for real single precision, x + = d = real double precision; - for real double precision, x = c = complex single precision; for complex single precision, x = z = complex double precision). This data - structure is accessed by the user only through the AMG4PSBLAS routines, +class="cmr-12">for following an object-oriented approach. +class="cmr-12">complex double precision;
      • -
    • 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. -
      • -
    • Build the preconditioner for a given matrix. If the selected preconditioner is - multilevel, then two steps must be performed, as specified next. -
        -
      1. Build the AMG hierarchy for a given matrix. This is performed by the - routine hierarchy_build. - - - -
        2. -
      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 preconditioner data structure must be of type amg_xprec_type, with x the routine bld. +class="cmr-12">= s, d, c, z, according to the sparse matrix data structure;
      • -
    • Apply the preconditioner at each iteration of a Krylov solver. This is performed by - the method apply. When using the PSBLAS Krylov solvers, this step is +
    • the arrays containing the vectors v and w involved in the preconditioner completely transparent to the user, since apply is called by the PSBLAS routine - implementing the Krylov solver (psb_krylov). +class="cmr-12">application w = B-1v must be of type psb_xvect_type with x = s, d, c, + z, in a manner completely analogous to the sparse matrix type;
      • -
    • Free the preconditioner data structure. This is performed by the routine free. +
    • real parameters defining the preconditioner must be declared according to This step is complementary to step 1 and should be performed when the +class="cmr-12">the precision of the sparse matrix and preconditioner data structures (see 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 -AMG4PSBLAS are reported in SectionSection 5.1. -

- - - -

- - - -
-

-

- - - - - - -
type

string

default preconditioner

No preconditioner

’NONE’

Considered to use the PSBLAS Krylov solvers -with no preconditioner.

Diagonal

’DIAG’, -’JACOBI’, -’L1-JACOBI’

Diagonal preconditioner. For any zero diagonal -entry of the matrix to be preconditioned, the -corresponding entry of the preconditioner is set -to 1.

Gauss-Seidel

’GS’, -’L1-GS’

Hybrid Gauss-Seidel (forward), that is, global -block Jacobi with Gauss-Seidel as local solver.

Symmetrized Gauss-Seidel

’FBGS’, -’L1-FBGS’

Symmetrized hybrid Gauss-Seidel, that is, -forward Gauss-Seidel followed by backward -Gauss-Seidel.

Block Jacobi

’BJAC’, -’L1-BJAC’

Block-Jacobi with ILU(0) on the local blocks.

Additive Schwarz

’AS’

Additive Schwarz (AS), 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, decoupled 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.

-
Table 1: Preconditioner types, corresponding strings and default choices.
-
+href="userhtmlsu8.html#x17-160005.2">5.2). +

A description of each method is given in the remainder of this section. -

-
-

Note that the module amg_prec_mod, containing the definition of the preconditioner -data type and the interfaces to the routines of AMG4PSBLAS, 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 shortest execution time -on parallel computers. -

DA MODIFICARE PER INSERIRE TIPO DI AGGREGAZIONE

 5.1 Examples +href="userhtmlsu7.html#x16-150005.1">Method init +
 5.2 Method set +
 5.3 Method hierarchy_build +
 5.4 Method smoothers_build +
 5.5 Method build +
 5.6 Method apply +
 5.7 Method free +
 5.8 Method descr +
 5.9 Auxiliary Methods +
  5.9.1 Method: dump +
  5.9.2 Method: clone +
  5.9.3 Method: sizeof +
  5.9.4 Method: allocate_wrk +
  5.9.5 Method: free_wrk
+ + + + + + + + -

[next] [up]

-

diff --git a/docs/html/userhtmlse6.html b/docs/html/userhtmlse6.html index 075c9956..b93d9fa5 100644 --- a/docs/html/userhtmlse6.html +++ b/docs/html/userhtmlse6.html @@ -1,7 +1,7 @@ -User Interface +Adding new smoother and solver objects to AMG4PSBLAS @@ -10,7 +10,7 @@ -

[nextup]

6 User Interface

-

The basic user interface of AMG4PBLAS consists of eight methods. The six methods -init, set, build, hierarchy_build, smoothers_build and apply encapsulate all the + id="x25-290006">Adding new smoother and solver objects to AMG4PSBLAS +

Developers can add completely new smoother and/or solver classes derived from the +base objects in the library (see Remark 2 in Section 5.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 functionalities for the setup and the application of any multilevel and one-level +class="cmr-12">“solver” object, which is almost always acting only on the local part of the distributed preconditioner implemented in the package. The method free deallocates the +class="cmr-12">matrix. The parallel actions required to connect the various solver objects are most preconditioner data structure, while descr prints a description of the preconditioner +class="cmr-12">often already provided by the block-Jacobi or the additive Schwarz smoothers. To setup by the user. For backward compatibility, methods are also accessible as +class="cmr-12">define a new solver, the developer will then have to define its components and stand-alone subroutines. -

For each method, the same user interface is overloaded with respect to the real/ +class="cmr-12">methods, perhaps taking one of the predefined solvers as a starting point, if complex case and the single/double precision; arguments with appropriate data types +class="cmr-12">possible. +

Once the new smoother/solver class has been developed, to use it in the context of must be passed to the method, i.e., +class="cmr-12">the multilevel preconditioners it is necessary to:

  • 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 preconditioner data structure must be of type amg_xprec_type, with x - = s, d, c, z, according to the sparse matrix data structure; +class="cmr-12">declare in the application program a variable of the new type;
  • the arrays containing the vectors v and w involved in the preconditioner - application w = B-1v must be of type psb_xvect_type with x = s, d, c, - z, in a manner completely analogous to the sparse matrix type; +class="cmr-12">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])

  • real parameters defining the preconditioner must be declared according to - the precision of the sparse matrix and preconditioner data structures (see +class="cmr-12">link the code implementing the various methods into the application Section 6.2).
-

A description of each method is given in the remainder of this section. +class="cmr-12">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 AMG4PSBLAS library has not been modified to account for this new +development. -

-  6.1 Method init -
 6.2 Method set -
 6.3 Method hierarchy_build -
 6.4 Method smoothers_build -
 6.5 Method build -
 6.6 Method apply -
 6.7 Method free -
 6.8 Method descr -
 6.9 Auxiliary Methods -
  6.9.1 Method: dump -
  6.9.2 Method: clone -
  6.9.3 Method: sizeof -
  6.9.4 Method: allocate_wrk -
  6.9.5 Method: free_wrk -
- - - - - +

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. By the same token, any keyword/value pair that does not +pertain to a given smoother should be passed down to the contained solver, and +any keyword/value pair that does not pertain to a given solver is by default +ignored. +

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(amg_x_base_smoother_type)

The user-defined new smoother to be employed in the +preconditioner.

solver

class(amg_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. 5.2. As an example, in the +tests/newslv code we define a new object of type amg_d_tlu_solver_type, and we +pass it as follows: + + + 

+  ! sparse matrix and preconditioner
+  type(psb_dspmat_type) :: a
+  type(amg_dprec_type)  :: prec
+  type(amg_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)
+
+

+ + + + -

[next] [up]

-

diff --git a/docs/html/userhtmlse7.html b/docs/html/userhtmlse7.html index e4454cff..de54f6e7 100644 --- a/docs/html/userhtmlse7.html +++ b/docs/html/userhtmlse7.html @@ -1,7 +1,7 @@ -Adding new smoother and solver objects to AMG4PSBLAS +Error Handling @@ -10,7 +10,7 @@ -

[nextup]

7 Adding new smoother and solver objects to AMG4PSBLAS

-

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 + id="x26-300007">Error Handling +

The error handling in AMG4PSBLAS is based on the PSBLAS error handling. Error often already provided by the block-Jacobi or the additive Schwarz smoothers. To +class="cmr-12">conditions are signaled via an integer argument info; whenever an error condition is define a new solver, the developer will then have to define its components and +class="cmr-12">detected, an error trace stack is built by the library up to the top-level, user-callable methods, perhaps taking one of the predefined solvers as a starting point, if +class="cmr-12">routine. This routine will then decide, according to the user preferences, whether possible. -

Once the new smoother/solver class has been developed, to use it in the context of +class="cmr-12">the error should be handled by terminating the program or by returning the 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])

    -
    • -
  • 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 +class="cmr-12">error condition to the user code, which will then take action, and whether the AMG4PSBLAS library has not been modified to account for this new +class="cmr-12">an error message should be printed. These options may be set by using the development. +class="cmr-12">PSBLAS error handling routines; for further details see the PSBLAS User’s Guide +[16]. -

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. By the same token, any keyword/value pair that does not -pertain to a given smoother should be passed down to the contained solver, and -any keyword/value pair that does not pertain to a given solver is by default -ignored. -

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(amg_x_base_smoother_type)

The user-defined new smoother to be employed in the -preconditioner.

solver

class(amg_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 amg_d_tlu_solver_type, and we -pass it as follows: - 

-  ! sparse matrix and preconditioner
-  type(psb_dspmat_type) :: a
-  type(amg_dprec_type)  :: prec
-  type(amg_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)
-
-

+

diff --git a/docs/html/userhtmlse8.html b/docs/html/userhtmlse8.html index 00aadf20..4d63ab74 100644 --- a/docs/html/userhtmlse8.html +++ b/docs/html/userhtmlse8.html @@ -1,7 +1,7 @@ -Error Handling +License @@ -12,7 +12,7 @@ >

[next] [up]

8 Error Handling

-

The error handling in AMG4PSBLAS is based on the PSBLAS 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 +class="cmr-12">A License +

AMG4PSBLAS is freely distributable under the following copyright terms: + + + + 

+                           AMG4PSBLAS  version 1.0
+              Algebraic MultiGrid Preconditioners Package
+             based on PSBLAS (Parallel Sparse BLAS version 3.7)
+  (C) Copyright 2021
+  Pasqua D’Ambra         IAC-CNR, IT
+  Fabio Durastante       University of Pisa and IAC-CNR, IT
+  Salvatore Filippone    University of Rome Tor-Vergata and IAC-CNR, 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.
+
+

+ + + +

AMG4PSBLAS is an evolution of MLD2P4, whose license we reproduce here to PSBLAS error handling routines; for further details see the PSBLAS User’s Guide -[16]. +class="cmr-12">abide by its terms: + 

+                           MLD2P4  version 2.2
+  MultiLevel Domain Decomposition Parallel Preconditioners Package
+             based on PSBLAS (Parallel Sparse BLAS version 3.5)
+  (C) Copyright 2008-2018
+      Salvatore Filippone
+      Pasqua D’Ambra
+      Daniela di Serafino
+  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.
+
+

+

-

[next] [] [up]

-

diff --git a/docs/html/userhtmlsu10.html b/docs/html/userhtmlsu10.html index 51b73ab8..3d27f940 100644 --- a/docs/html/userhtmlsu10.html +++ b/docs/html/userhtmlsu10.html @@ -1,7 +1,7 @@ -Method init +Method smoothers_build @@ -10,92 +10,187 @@ -

[next] [prev] [prev-tail] [tail] [up]

6.1 Method init

+class="cmr-12">5.4 Method smoothers_build
-

-

+

call p%init(icontx,ptype,info)

-

This method allocates and initializes the preconditioner p, according to the +class="cmtt-12"> p%smoothers_build(a,desc_a,p,info[,amold,vmold,imold])
+

+

This method builds the smoothers and the coarsest-level solvers for the multilevel preconditioner type chosen by the user. -

preconditioner p, according to the requirements made by the user through the methods +init and set, and based on the aggregation hierarchy produced by a previous call to +hierarchy_build (see Section 5.3). +

Arguments -

+class="cmr-12">. + style="vertical-align:baseline;" id="TBL-12-2-"> + style="vertical-align:baseline;" id="TBL-12-3-"> + style="vertical-align:baseline;" id="TBL-12-4-"> + + + + + +

icontxt

integer,

a

type(psb_xspmat_type), intent(in).

The communication context.

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 AMG4PSBLAS +under use. See the PSBLAS User’s Guide for details [16].

The type of preconditioner. Its values are specified in Table 1.

desc_a

type(psb_desc_type), intent(in).

Note that the strings are case insensitive.

The communication descriptor of a. See the PSBLAS User’s Guide +for details [16].

info

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 8 7 for details.

amold

class(psb_x_base_sparse_mat), intent(in), optional.

The desired dynamic type for internal matrix components; this +allows e.g. running on GPUs; it needs not be the same on all +processes. See the PSBLAS User’s Guide for details [16].

vmold

class(psb_x_base_vect_type), intent(in), optional.

The desired dynamic type for internal vector components; this +allows e.g. running on GPUs.

imold

class(psb_i_base_vect_type), intent(in), optional.

The desired dynamic type for internal integer vector components; +this allows e.g. running on GPUs.

@@ -103,17 +198,23 @@ class="td11">
-

[next] [prev] [prev-tail] [front] [up]

-

diff --git a/docs/html/userhtmlsu11.html b/docs/html/userhtmlsu11.html index 996eaf4b..d9405f3c 100644 --- a/docs/html/userhtmlsu11.html +++ b/docs/html/userhtmlsu11.html @@ -1,7 +1,7 @@ -Method set +Method build @@ -10,7 +10,7 @@ -

[next] [tail] [up]

6.2 Method set

+class="cmr-12">5.5 Method build
-

-

+

call p%set(what,val,info [,ilev, ilmax, pos, idx])

-

This method 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 p%build(a,desc_a,info[,amold,vmold,imold])
+ +

This method builds the preconditioner p according to the requirements made by the +user through the methods init and set (see Sections 2-8.

val 

integer or character(len=*) or real(psb_spk_) or -real(psb_dpk_), intent(in).

The value of the parameter to be set. The list of allowed values and -the corresponding data types is given in Tables5.3 and 2-8. When the value +href="userhtmlsu10.html#x19-180005.4">5.4 for multilevel 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 multilevel preconditioner, the level at which the -preconditioner parameter has to be set. The levels are numbered +class="cmr-12">preconditioners). It is mostly provided for backward compatibility; indeed, it is 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 +class="cmr-12">internally implemented by invoking the two previous methods hierarchy_build and +smoothers_build, whose nomenclature would however be somewhat unnatural when is set at all the appropriate levels (see Tables 2-8).

ilmax

integer, optional,dealing with simple one-level preconditioners. +

Arguments +

+class="cmr-12">. - + +class="cmr-12">. - + +class="cmtt-12"> intent(out). -

a

type(psb_xspmat_type), intent(in).

For the multilevel preconditioner, when both ilev and ilmax are + style="vertical-align:baseline;" id="TBL-13-2-">

The sparse matrix structure containing the local part of the matrix present, the settings are applied at all levels ilev:ilmax. When -ilev is present but ilmax is not, then the default is ilmax=ilev. +class="cmr-12">to be preconditioned. Note that x must be chosen according to the The levels are numbered in increasing order starting from the finest +class="cmr-12">real/complex, single/double precision version of AMG4PSBLAS one, i.e., level 1 is the finest level.

pos

charater(len=*), optional,under use. See the PSBLAS User’s Guide for details [16].

desc_a

type(psb_desc_type), 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 + style="vertical-align:baseline;" id="TBL-13-4-">

The communication descriptor of a. See the PSBLAS User’s Guide not concern the smoothers, pos is ignored.

idx

for details [16].

info

integer, optional, intent(in).

An auxiliary input argument that can be passed to the underlying -objects.

-

However, in this case the optional arguments ilev, ilmax, pos and idx 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 -

    -
  1. the type of multilevel cycle and how many cycles must be applied; -
    2. -
  2. the coarsening algorithm; -
    3. -
  3. the coarse-space correction at the coarsest level (for multilevel - preconditioners only); - - - -
    4. -
  4. the smoother of the multilevel 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.
-

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 point-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. -

Remark 4. The argument idx can be used to allow finer control for those solvers; -for instance, by specifying the keyword MUMPS_IPAR_ENTRY and an appropriate value -for idx, it is possible to set any entry in the MUMPS integer control array. See also -Sec.

Error code. If no error, 0 is returned. See Section 7. -

- - - -

- - - -
-

-

- -

what

data type

val

default

comments

’ML_CYCLE’

character(len=*)

’VCYCLE’ -

’WCYCLE’ -

’KCYCLE’ -

’ADD’

’VCYCLE’

Multilevel cycle: V-cycle, W-cycle, K-cycle, -and additive composition.

’OUTER_SWEEPS’

integer

Any integer -

number ≥ 1

1

Number of multilevel cycles.

-
Table 2: Parameters defining the multilevel cycle and the number of cycles to be -applied.
- - - -
-
-
- - - -

- - - -
-

- - - -

- - - - - - - -
Note. The aggregation algorithm stops when at least one of the following criteria is met: the coarse size threshold, the coarse size threshold per process, the
-
minimum 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.
-

what

data type

val

default

comments

’MIN_COARSE_SIZE_PER_PROCESS’

integer

Any number -

> 0

200

Coarse size threshold per process. The -aggregation stops if the global number of -variables of the computed coarsest matrix -is lower than or equal to this threshold -multiplied by the number of processes. -

’MIN_COARSE_SIZE’

integer

Any number -

> 0

-1

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). If negative, -it is ignored in favour of the default for -’MIN_COARSE_SIZE_PER_PROCESS’.

’MIN_CR_RATIO’

real

Any number -

> 1

1.5

Minimum coarsening -ratio. The aggregation stops if the ratio -between the global matrix dimensions at -two consecutive levels is lower than or -equal to this threshold (see Note).

’MAX_LEVS’

integer

Any integer -

number > 1

20

Maximum number of levels. The -aggregation stops if the number of levels -reaches this value (see Note).

’PAR_AGGR_ALG’

character(len=*)

’DEC’, -’SYMDEC’, -’COUPLED’

’DEC’

Parallel aggregation algorithm. -

the SYMDEC option applies decoupled -aggregation to the sparsity pattern of -A + AT .

’AGGR_TYPE’

character(len=*)

’SOC1’

’SOC1’, -’SOC2’, -’MATCHBOXP’

Type of aggregation algorithm: currently, -for the -decoupled aggregation we implement two -measures of strength of connection, the -one by Vaněk, Mandel and Brezina [29], -and the one by Gratton et al [19]. The -coupled aggregation is based on a parallel -version of the half-approximate matching -implemented in the MatchBox-P software -package AGGIUNGERE LINK AL -PACKAGE?

’AGGR_SIZE’

integer

Any integer -

number -power of 2 -and > 2

4

Maximum size of aggregates when the -coupled aggregation based on matching -is applied. For aggressive coarsening -with size of aggregate larger than 8 -we recommend the use of smoothed -prolongators. MODIFICARE -CODICE

’AGGR_PROL’

character(len=*)

’SMOOTHED’, -’UNSMOOTHED’

’SMOOTHED’

Prolongator used by the aggregation -algorithm: smoothed or unsmoothed (i.e., -tentative prolongator).

- - -
-
Table 3: Parameters defining the aggregation algorithm.
- - - -
-
-
- - - -

- - - -
-

-

- - -
Note. Different thresholds at different levels, such as those used in [29, Section 5.1], can be easily set by invoking the rou-
+href="userhtmlse7.html#x26-300007">7for details.
tine set with the parameter ilev.
-

what

data type

val

default

comments

’AGGR_ORD’

character(len=*)

’NATURAL’ -

’DEGREE’

’NATURAL’

Initial ordering of indices for -the decoupled 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,1]

0.01

The threshold θ in the decoupled -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).

-
Table 4: Parameters defining the aggregation algorithm (continued).
- - - -
-
-
- - - -

- - - -
-

-

- - -
Note. Defaults for COARSE_SOLVE and COARSE_SUBSOLVE are chosen in the following order:
+ style="vertical-align:baseline;" id="TBL-13-7-"> +
single precision version – MUMPS if installed, then SLU if installed, ILU otherwise;
+ style="vertical-align:baseline;" id="TBL-13-9-">
double precision version – UMF if installed, then MUMPS if installed, then SLU if installed, ILU otherwise.
-

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’ -

’PCG’

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 and related -ℓ1-versions; -preconditioned Conjugate Gradient coupled -with the block-Jacobi preconditioner with -ILU(0) on the blocks. -

Note that UMF and SLU require the coarsest matrix -to be replicated, SLUDIST, JACOBI, GS, BJAC and PCG -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 -of the solver (see Remark 3, p. 24). Note also that -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(p), ILU(p,t), MILU(p), -LU from MUMPS, SuperLU or UMFPACK -(plus triangular solve). Aggiungere Sparse -Approssimate per GPU? Note that UMFPACK -and SuperLU_Dist are available only in double -precision.

amold

class(psb_x_base_sparse_mat), intent(in), optional.

The desired dynamic type for internal matrix components; this +allows e.g. running on GPUs; it needs not be the same on all +processes. See the PSBLAS User’s Guide for details [16].

vmold

class(psb_x_base_vect_type), intent(in), optional.

-
Table 5: Parameters defining the coarse-space correction at the coarsest level.
- - - -
-
-
- - - -

- - - -
-

-

- - -

what

data type

val

default

comments

’COARSE_SWEEPS’

integer

Any integer -

number > 0

10

Number of sweeps when JACOBI, GS or BJAC is -chosen as coarsest-level solver. Aggiungere -criterio di arresto del PCG?

’COARSE_FILLIN’

integer

Any integer -

number ≥ 0

0

Fill-in level p of the ILU factorizations.

’COARSE_ILUTHRS’

real(kind_parameter)

Any real -

number ≥ 0

0

Drop tolerance t in the ILU(p,t) -factorization.

-
Table 6: Parameters defining the coarse-space correction at the coarsest level -(continued).
- - - -
-
-
- - - -

- - - -
-

-

- - - -

what

data type

val

default

comments

’SMOOTHER_TYPE’

character(len=*)

’JACOBI’ -

’GS’ -

’BGS’ -

’BJAC’ -

’AS’

’FBGS’

Type of smoother used in the multilevel -preconditioner: point-Jacobi, hybrid -(forward) Gauss-Seidel, hybrid backward -Gauss-Seidel, block-Jacobi, ℓ1-versions? -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 -multilevel -preconditioners, -respectively -

ILU for block-Jacobi -and Additive Schwarz -one-level -preconditioners -ℓ1-versions?

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(p), ILU(p,t), MILU(p), -LU from MUMPS, SuperLU -or UMFPACK (plus triangular solve). See -Note for details on hybrid Gauss-Seidel.

’SMOOTHER_SWEEPS’

integer

Any integer -

number ≥ 0

1

Number of sweeps of the smoother or -one-level preconditioner. In the multilevel -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 ≥ 0

1

Number of overlap layers, for Additive + style="vertical-align:baseline;" id="TBL-13-10-">

The desired dynamic type for internal vector components; this Schwarz only.

-
Table 7: Parameters defining the smoother or the details of the one-level -preconditioner.
- - - -
-
-
- - - -

- - - -
-

-

- - - +class="cmr-12">allows e.g. running on GPUs. + style="vertical-align:baseline;" id="TBL-13-11-"> +class="cmr-12">this allows e.g. running on GPUs. -

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

0

Fill-in level p of the incomplete LU -factorizations.

’SUB_ILUTHRS’

real(kind_parameter)

Any real -number ≥ 0

0

Drop tolerance t in the ILU(p,t) factorization.

’MUMPS_LOC_GLOB’

character(len=*)

LOCAL_SOLVER’ -

GLOBAL_SOLVER’

GLOBAL_SOLVER’

Whether MUMPS should be used as a -distributed solver, or as a serial solver acting -only on the part of the matrix local to each -process.

imold

class(psb_i_base_vect_type), intent(in), optional.

’MUMPS_IPAR_ENTRY’

integer

Any integer + style="vertical-align:baseline;" id="TBL-13-12-">

The desired dynamic type for internal integer vector components; number

0

Set an entry in the MUMPS integer control -array, as chosen via the idx optional argument.

’MUMPS_RPAR_ENTRY’

real

Any real -number

0

Set an entry in the MUMPS real control array, -as chosen via the idx optional argument.

-
Table 8: Parameters defining the smoother or the details of the one-level preconditioner -(continued).
- - - -
-
+ style="vertical-align:baseline;" id="TBL-13-13-">
+

The method can be used to build multilevel preconditioners too. -

[next] [front] [up]

-

diff --git a/docs/html/userhtmlsu12.html b/docs/html/userhtmlsu12.html index 68a0faf8..c37a2365 100644 --- a/docs/html/userhtmlsu12.html +++ b/docs/html/userhtmlsu12.html @@ -1,7 +1,7 @@ -Method hierarchy_build +Method apply @@ -10,7 +10,7 @@ -

[next] [tail] [up]

6.3 Method hierarchy_build

+class="cmr-12">5.6 Method apply
-

-

+

call p%hierarchy_build(a,desc_a,info)
+class="cmtt-12"> p%apply(x,y,desc_a,info [,trans,work])

-

This method builds the hierarchy of matrices and restriction/prolongation operators for +

This method computes y = op(B-1) x, where B is a previously built preconditioner, the multilevel preconditioner stored into p, according to the requirements made by the user +class="cmr-12">, and op denotes the preconditioner itself or its transpose, according to the through the methods init and set. -

value of trans. Note that, when AMG4PSBLAS is used with a Krylov solver from +PSBLAS, p%apply is called within the PSBLAS method psb_krylov and hence it is +completely transparent to the user. +

Arguments -

+class="cmr-12">. + + +class="cmr-12">precision version of AMG4PSBLAS under use. +class="cmr-12">preconditioned. + + + +

a

type(psb_xspmat_type),

x

type(kind_parameter), dimension(:), intent(in).

The sparse matrix structure containing the local part of the matrix + style="vertical-align:baseline;" id="TBL-14-2-">

The local part of the vector x. Note that type and kind_parameter to be preconditioned. Note that x must be chosen according to the +class="cmr-12">must be chosen according to the real/complex, single/double +precision version of AMG4PSBLAS under use.

y

type(kind_parameter), dimension(:), intent(out).

The local part of the vector y. Note that type and kind_parameter real/complex, single/double precision version of AMG4PSBLAS +class="cmr-12">must be chosen according to the real/complex, single/double under use. See the PSBLAS User’s Guide for details [16].

desc_a

desc_a

type(psb_desc_type), intent(in).

The communication descriptor of a. See the PSBLAS User’s Guide + style="vertical-align:baseline;" id="TBL-14-6-">

The communication descriptor associated to the matrix to be for details [16].

info

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 8 7 for details.

trans

character(len=1), optional, intent(in).

If trans = ’N’,’n’ then op(B-1) = B-1; if trans = ’T’,’t’ +then op(B-1) = B-T (transpose of B-1); if trans = ’C’,’c’ then +op(B-1) = B-C (conjugate transpose of B-1).

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 AMG4PSBLAS under use.

@@ -133,7 +272,7 @@ class="td11">
-

[next] [front] [up]

-

diff --git a/docs/html/userhtmlsu13.html b/docs/html/userhtmlsu13.html index 301f0301..beacd7e1 100644 --- a/docs/html/userhtmlsu13.html +++ b/docs/html/userhtmlsu13.html @@ -1,7 +1,7 @@ -Method smoothers_build +Method free @@ -10,7 +10,7 @@ -

[next] [tail] [up]

6.4 Method smoothers_build

+class="cmr-12">5.7 Method free
-

-

+

call p%smoothers_build(a,desc_a,p,info[,amold,vmold,imold])
+class="cmtt-12"> p%free(p,info)

-

This method builds the smoothers and the coarsest-level solvers for the multilevel -preconditioner

This method deallocates the preconditioner data structure p, according to the requirements made by the user through the methods -init and set, and based on the aggregation hierarchy produced by a previous call to -hierarchy_build (see Section 6.3). -

. +

Arguments -

- - - - +class="cmr-12">. - - - - - - +class="cmr-12">details.

a

type(psb_xspmat_type), 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 AMG4PSBLAS -under use. See the PSBLAS User’s Guide for details [16].

desc_a

type(psb_desc_type), intent(in).

The communication descriptor of a. See the PSBLAS User’s Guide -for details [16].

info

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 8 for details.

amold

class(psb_x_base_sparse_mat), intent(in), optional.

The desired dynamic type for internal matrix components; this -allows e.g. running on GPUs; it needs not be the same on all -processes. See the PSBLAS User’s Guide for details [16].

vmold

class(psb_x_base_vect_type), intent(in), optional.

The desired dynamic type for internal vector components; this -allows e.g. running on GPUs.

imold

class(psb_i_base_vect_type), intent(in), optional.

The desired dynamic type for internal integer vector components; +href="userhtmlse7.html#x26-300007">7 for this allows e.g. running on GPUs.

@@ -198,7 +76,7 @@ class="td11">
-

[next] [front] [up]

-

diff --git a/docs/html/userhtmlsu14.html b/docs/html/userhtmlsu14.html index 169ada07..33c1f741 100644 --- a/docs/html/userhtmlsu14.html +++ b/docs/html/userhtmlsu14.html @@ -1,7 +1,7 @@ -Method build +Method descr @@ -10,7 +10,7 @@ -

[next] [tail] [up]

6.5 Method build

+class="cmr-12">5.8 Method descr
-

-

+

call p%build(a,desc_a,info[,amold,vmold,imold])
+class="cmtt-12"> p%descr(info, [iout])

-

This method builds the preconditioner

This method prints a description of the preconditioner p according to the requirements made by the +class="cmr-12">to the standard output or to a user through the methods init file. It must be called after hierachy_build and set (see Sections 6.3 and 6.4 for multilevel -preconditioners). It is mostly provided for backward compatibility; indeed, it is -internally implemented by invoking the two previous methods hierarchy_build and -smoothers_build, whose nomenclature would however be somewhat unnatural when +class="cmr-12">, or build, have dealing with simple one-level preconditioners. -

been called. +

Arguments -

- - - - - - - - +class="cmr-12">. +class="cmr-12">printed; the default is the standard output.

a

type(psb_xspmat_type), 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 AMG4PSBLAS -under use. See the PSBLAS User’s Guide for details [16].

desc_a

type(psb_desc_type), intent(in).

The communication descriptor of a. See the PSBLAS User’s Guide -for details [16].

info

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 8 7 for details.

amold

class(psb_x_base_sparse_mat), intent(in), optional.

The desired dynamic type for internal matrix components; this -allows e.g. running on GPUs; it needs not be the same on all -processes. See the PSBLAS User’s Guide for details [16].

vmold

class(psb_x_base_vect_type), intent(in), optional.

The desired dynamic type for internal vector components; this -allows e.g. running on GPUs.

imold

class(psb_i_base_vect_type),

iout

integer, intent(in), optional.

The desired dynamic type for internal integer vector components; + style="vertical-align:baseline;" id="TBL-16-4-">

The id of the file where the preconditioner description will be this allows e.g. running on GPUs.

-

The method can be used to build multilevel preconditioners too. - - - -

[next] [front] [up]

-

diff --git a/docs/html/userhtmlsu15.html b/docs/html/userhtmlsu15.html index 5528bbf1..e5cffe49 100644 --- a/docs/html/userhtmlsu15.html +++ b/docs/html/userhtmlsu15.html @@ -1,7 +1,7 @@ -Method apply +Auxiliary Methods @@ -10,11 +10,8 @@ -

[next] [prev] [] [tail] [up]

6.6 Method apply

+class="cmr-12">5.9 Auxiliary Methods +

Various functionalities are implemented as additional methods of the preconditioner +object. +

+

5.9.1 Method: dump
-

-

+

call p%apply(x,y,desc_a,info [,trans,work])
+class="cmtt-12"> p%dump(info[,istart,iend,prefix,head,ac,rp,smoother,solver,global_num])

-

This method computes y = op(B-1) x, where B is a previously built preconditioner, -stored into p, and op denotes the preconditioner itself or its transpose, according to the -value of trans. Note that, when AMG4PSBLAS is used with a Krylov solver from -PSBLAS, p%apply is called within the PSBLAS method psb_krylov and hence it is -completely transparent to the user. -

Dump on file. +

Arguments -

+> + + +class="cmr-12">processes. See the PSBLAS User’s Guide for details [16].

x

type(kind_parameter), dimension(:), intent(in).

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 7 for details.

amold

class(psb_x_base_sparse_mat), intent(in), optional.

The local part of the vector x. Note that type and kind_parameter + style="vertical-align:baseline;" id="TBL-17-4-">

The desired dynamic type for internal matrix components; this must be chosen according to the real/complex, single/double +class="cmr-12">allows e.g. running on GPUs; it needs not be the same on all precision version of AMG4PSBLAS under use.

y

type(kind_parameter), dimension(:),
+

+

5.9.2 Method: clone
+
+

+

call p%clone(pout,info)
+

+ + + +

Create a (deep) copy of the preconditioner object. +

Arguments +

+class="cmr-12">. +class="cmr-12">version of AMG4PSBLAS under use. + style="vertical-align:baseline;" id="TBL-18-3-"> + style="vertical-align:baseline;" id="TBL-18-4-">

pout

type(amg_xprec_type), intent(out).

The local part of the vector y. Note that type and kind_parameter + style="vertical-align:baseline;" id="TBL-18-2-">

The copy of the preconditioner data structure. Note that x must must be chosen according to the real/complex, single/double +class="cmr-12">be chosen according to the real/complex, single/double precision precision version of AMG4PSBLAS under use.

desc_a

type(psb_desc_type), intent(in).

info

integer, intent(out).

The communication descriptor associated to the matrix to be -preconditioned.

Error code. If no error, 0 is returned. See Section 7 for details.

info

+

+

5.9.3 Method: sizeof
+
+

+

sz =  p%sizeof()
+

+

Return memory footprint in bytes. +

+

5.9.4 Method: allocate_wrk
+
+

+

call p%allocate_wrk(info[, vmold])
+

+

Allocate internal work vectors. Each application of the preconditioner uses a number of +work vectors which are allocated internally as necessary; therefore allocation and +deallocation of memory occurs multiple times during the execution of a Krylov method. +In most cases this strategy is perfectly acceptable, but on some platforms, most +notably GPUs, memory allocation is a slow operation, and the default behaviour would +lead to a slowdown. This method allows to trade space for time by preallocating +the internal workspace outside of the invocation of a Krylov method. When +using GPUs or other specialized devices, the vmold argument is also necessary +to ensure the internal work vectors are of the appropriate dynamic type to + + + +exploit the accelerator hardware; when allocation occurs internally this is +taken care of based on the dynamic type of the x argument to the apply +method. +

Arguments +

+ style="vertical-align:baseline;" id="TBL-19-3-"> +class="cmr-12">allows e.g. running on GPUs. + style="vertical-align:baseline;" id="TBL-19-5-">

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 8 7 for details.

trans

character(len=1), optional, intent(in).

vmold

class(psb_x_base_vect_type), intent(in), optional.

If trans = ’N’,’n’ then op(B-1) = B-1; if trans = ’T’,’t’ + style="vertical-align:baseline;" id="TBL-19-4-">

The desired dynamic type for internal vector components; this then op(B-1) = B-T (transpose of B-1); if trans = ’C’,’c’ then -op(B-1) = B-C (conjugate transpose of B-1).

work

type(kind_parameter), dimension(:), optional, target.

+

+

5.9.5 Method: free_wrk
+
+

+

call p%free_wrk(info)
+

+

Deallocate internal work vectors. +

Arguments +

+ style="vertical-align:baseline;" id="TBL-20-2-">

info

integer, intent(out).

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 AMG4PSBLAS under use.

Error code. If no error, 0 is returned. See Section 7 for details.

@@ -272,11 +314,11 @@ class="td11">
-

[next] [prev] [] [front] [up]

-

+

diff --git a/docs/html/userhtmlsu5.html b/docs/html/userhtmlsu5.html index 180920d1..4144195d 100644 --- a/docs/html/userhtmlsu5.html +++ b/docs/html/userhtmlsu5.html @@ -81,6 +81,12 @@ class="cmr-12">partial differential equation. + + + + + +

[ -AMG preconditioners +Examples @@ -10,11 +10,8 @@ -

[next] [tail] []

4.1 AMG preconditioners

-

In order to describe the AMG preconditioners available in MLD2P4, we consider a -linear system -
-
-Ax = b, -
(2)
-

-where A = (aij) ∈ ℝn×n is a nonsingular sparse matrix; for ease of presentation we -assume A has a symmetric sparsity pattern. +class="cmr-12">Examples +

The code reported in Figure 1 shows how to set and apply the default multilevel +preconditioner available in the real double precision version of AMG4PSBLAS +(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, amg_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 amg_dexample_ml.f90, in the +directory examples/fileread of the AMG4PSBLAS 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 [16]. +

The setup and application of the default multilevel preconditioner for the real single -

Let us consider as finest index space the set of row (column) indices of A, -i.e., Ω = {1, 2,…,n}. Any algebraic multilevel preconditioners implemented in -MLD2P4 generates a hierarchy of index spaces and a corresponding hierarchy of -matrices, -

- 1 2 nlev 1 2 nlev -Ω ≡ Ω ⊃ Ω ⊃ ...⊃ Ω , A ≡ A, A ,...,A , -
-

by using the information contained in A, without assuming any knowledge of -the geometry of the problem from which A originates. A vector space ℝnk is -associated with Ωk, where n -k is the size of Ωk. For all k < nlev, a restriction -operator and a prolongation one are built, which connect two levels k and -k + 1: -

-P k ∈ ℝnk×nk+1, Rk ∈ ℝnk+1×nk ; -
-

the matrix Ak+1 is computed by using the previous operators according to the -Galerkin approach, i.e., -

- k+1 k k k -A = R A P . -
-

In the current implementation of MLD2P4 we have Rk = (Pk)T A smoother with -iteration matrix Mk is set up at each level k < nlev, 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 LU factorization means computing and storing the L and U factors). The -construction of the hierarchy of AMG components described so far corresponds to the -so-called build phase of the preconditioner. -

precision and the complex, single and double precision, versions are obtained +with straightforward modifications of the previous example (see Section 5 for +details). If these versions are installed, the corresponding codes are available in +examples/fileread/. +

+ id="x14-130011">
-

-

-

procedure V-cycle( k k k) - k,A ,b ,u -
-

-
if (k ⁄= nlev) then
-

-
uk = uk + Mk( ) - bk - Akuk
-

-
bk+1 = Rk+1(bk - Akuk )
-

-
uk+1 = V-cycle( ) - k + 1,Ak+1,bk+1,0
-

-
uk = uk + Pk+1uk+1
-

-
uk = uk + Mk( ) - bk - Akuk
-

-
else
-

-
uk = ( ) - Ak-1bk
-

-
endif
-

-
return uk
-

-
end
-

+

+ + + +

+  use psb_base_mod
+  use amg_prec_mod
+  use psb_krylov_mod
+... ...
+!
+! sparse matrix
+  type(psb_dspmat_type) :: A
+! sparse matrix descriptor
+  type(psb_desc_type)   :: desc_A
+! preconditioner
+  type(amg_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 multilevel 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
+
+

+ + +


Figure 1: Application phase of a V-cycle preconditioner.
+class="content">setup and application of the default multilevel preconditioner (example 1).
-

-

The components produced in the build phase may be combined in several ways to +

+

Different versions of the multilevel preconditioner can be obtained by changing the obtain different multilevel preconditioners; this is done in the application phase, i.e., in +class="cmr-12">default values of the preconditioner parameters. The code reported in Figure 2 shows the computation of a vector of type w = B-1v, where B denotes the preconditioner, +class="cmr-12">how to set a V-cycle preconditioner which applies 1 block-Jacobi sweep as pre- and usually within an iteration of a Krylov solver [24]. An example of such a combination, +class="cmr-12">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. known as V-cycle, is given in FigureFigure 1. In this case, a single iteration of the same +href="#x14-130033">3 shows how to set a W-cycle preconditioner using the Coarsening smoother is used before and after the the recursive call to the V-cycle (i.e., in the +class="cmr-12">based on Compatible Weighted Matching. It applies 2 hybrid Gauss-Seidel pre-smoothing and post-smoothing phases); however, different choices can be +class="cmr-12">sweeps as pre- and post-smoother, and solves the coarsest-level system with the performed. Other cycles can be defined; in MLD2P4, we implemented the +class="cmr-12">multifrontal LU factorization implemented in MUMPS. It is specified that the standard V-cycle and W-cycle [3], and a version of the K-cycle described +class="cmr-12">coarsest-level matrix is distributed, since MUMPS can be used on both replicated and in [23]distributed matrices, and by default it is used on replicated ones. The code +fragments shown in Figures 2 and 3 are included in the example program file +amg_dexample_ml.f90 too. DA CORREGGERE NEL CODICE ESEMPIO +3 +

Finally, Figure 4 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 +amg_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. +

+ + + + + + + +
+

+

+... ...
+! 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 2: setup of a multilevel preconditioner based on the default decoupled coarsening
+
-

+

+ + + + + + + +
+

+

+... ...
+! 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(’PAR_AGGR_ALG’,’COUPLED’,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 3: setup of a multilevel preconditioner based on the coupled coarsening based +on weighted matching
+
+ + + +

+

+ + + + + + + +
+

+

+... ...
+! 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)
+
+

+
Figure 4: setup of a one-level Schwarz preconditioner.
+
+ + + +

+ + + + + + +

[next] [front] [up]

-

diff --git a/docs/html/userhtmlsu7.html b/docs/html/userhtmlsu7.html index 2927d515..52867ea7 100644 --- a/docs/html/userhtmlsu7.html +++ b/docs/html/userhtmlsu7.html @@ -1,7 +1,7 @@ -Smoothed Aggregation +Method init @@ -10,386 +10,110 @@ -

[next] [prev] [prev-tail] [tail] [up]

4.2 Smoothed Aggregation

-

In order to define the prolongator Pk, used to compute the coarse-level matrix Ak+1, -MLD2P4 uses the smoothed aggregation algorithm described in [2,5.1 Method init +

+

+

call p%init(icontx,ptype,info)

+

This method allocates and initializes the preconditioner p, according to the +preconditioner type chosen by the user. +

Arguments +

+ + + + + +

icontxt

integer, intent(in).

The communication context.

ptype

character(len=*), intent(in).

The type of preconditioner. Its values are specified in Table 29]. The basic idea -of this algorithm is to build a coarse set of indices Ωk+1 by suitably grouping the -indices of Ωk into disjoint subsets (aggregates), and to define the coarse-to-fine space -transfer operator Pk 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: -

    -
  1. aggregation of the indices of Ωk to obtain Ωk+1; -
    2. -
  2. construction of the prolongator Pk; -
    3. -
  3. application of Pk and Rk = (Pk)T to build Ak+1.
-

In order to perform the coarsening step, the smoothed aggregation algorithm -described in [29] is used. In this algorithm, each index j ∈ Ωk+1 corresponds -to an aggregate Ωjk of Ωk, consisting of a suitably chosen index i ∈ Ωk and -indices that are (usually) contained in a strongly-coupled neighborood of i, -i.e., -
-
- { ∘ -------} -Ωkj ⊂ N ki (θ) = r ∈ Ωk : |akir| > θ |akiiakrr| ∪ {i} , -
(3)
+href="userhtmlse4.html#x13-120151">1.

Note that the strings are case insensitive.

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 7 for details.

-

-for a given threshold θ ∈ [0, 1] (see [29] 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 A. Nevertheless, this parallel algorithm has been chosen -for MLD2P4, since it has been shown to produce good results in practice -[5, 8, 28]. -

The prolongator Pk is built starting from a tentative prolongator Pk ∈ ℝnk×nk+1, -defined as -
-
- { k -P¯k = (¯pkij), p¯kij = 1 if i ∈ Ω j, - 0 otherwise, -
(4)
-

-where Ωjk is the aggregate of Ωk corresponding to the index j ∈ Ωk+1. Pk is obtained -by applying to Pk a smoother Sk ∈ ℝnk×nk: -

-Pk = Sk ¯Pk,
in -order to remove nonsmooth components from the range of the prolongator, and hence -to improve the convergence properties of the multilevel method [2, 27]. A simple -choice for Sk is the damped Jacobi smoother: -
- k k k -1 k -S = I - ω (D ) A F, -
-

where Dk is the diagonal matrix with the same diagonal entries as Ak, A -F k = (a -ijk) is -the filtered matrix defined as -
-
- { k k ∑ -a¯kij = aij if j ∈ N i (θ), (j ⁄= i), ¯akii = akii - (akij - ¯akij), - 0 otherwise, j⁄=i -
(5)
-

-and ωk is an approximation of 4∕(3ρk), where ρk is the spectral radius of (Dk)-1A -F k -[2]. In MLD2P4 this approximation is obtained by using ∥AF k∥ -∞ as an estimate of ρk. -Note that for systems coming from uniformly elliptic problems, filtering the matrix Ak -has little or no effect, and Ak can be used instead of A -F k. The latter choice is the -default in MLD2P4. -

[next] [prev] [prev-tail] [front] [up]

-

diff --git a/docs/html/userhtmlsu8.html b/docs/html/userhtmlsu8.html index 0063d7d0..a8b8e73d 100644 --- a/docs/html/userhtmlsu8.html +++ b/docs/html/userhtmlsu8.html @@ -1,7 +1,7 @@ -Smoothers and coarsest-level solvers +Method set @@ -10,8 +10,11 @@ -

[next] [prev] [] [tail] [up]

4.3 Smoothers and coarsest-level solvers

-

The smoothers implemented in MLD2P4 include the Jacobi and block-Jacobi methods, +class="cmr-12">5.2 Method set +

+

+

call p%set(what,val,info [,ilev, ilmax, pos, idx])

+

This method sets the parameters defining the preconditioner p. More precisely, the a hybrid version of the forward and backward Gauss-Seidel methods, and the additive +class="cmr-12">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 Schwarz (AS) ones (see, e.g., [24,string is case-insensitive. See Tables 25]). -

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 Ωk is divided into m -k subsets Ωik of -size nk,i, possibly overlapping. For each i we consider the restriction operator -Rik ∈ ℝnk,i×nk that maps a vector xk to the vector x -ik made of the components of -xk with indices in Ω -ik, and the prolongation operator P -ik = (R -ik)T . These -operators are then used to build Aik = R -ikAkP -ik, which is the restriction of -Ak to the index space Ω -ik. The classical AS preconditioner M -ASk is defined -as -

- m∑k -(M AkS )-1 = Pki (Aki)-1Rki, - i=1 -
-

where Aik is supposed to be nonsingular. We observe that an approximate inverse of -Aik is usually considered instead of (A -ik)-1. The setup of M -ASk during the multilevel -build phase involves -

    -
  • the definition of the index subspaces Ωik and of the corresponding operators - Rik (and P -ik); +href="#x17-160092">2-8.

val 

integer or character(len=*) or real(psb_spk_) or +real(psb_dpk_), intent(in).

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 7 for details.

ilev

integer, optional, intent(in).

For the multilevel 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 multilevel 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.

idx

integer, optional, intent(in).

An auxiliary input argument that can be passed to the underlying +objects.

+

However, in this case the optional arguments ilev, ilmax, pos and idx 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 +

    +
  1. the type of multilevel cycle and how many cycles must be applied;
    2. -
  2. the computation of the submatrices Aik; +
  3. the coarsening algorithm;
    4. -
  4. the computation of their inverses (usually approximated through some form +
  5. the coarse-space correction at the coarsest level (for multilevel of incomplete factorization).
    6. +class="cmr-12">preconditioners only); -

    The computation of zk = M -ASkwk, with wk ∈ ℝnk, during the multilevel application -phase, requires -

      -
    • the restriction of wk to the subspaces ℝnk,i, i.e. w -ik = R -ikwk; -
      • -
    • the computation of the vectors zik = (A -ik)-1w -ik;
      • -
    • the prolongation and the sum of the previous vectors, i.e. zk = +
    • the smoother of the multilevel preconditioners, or the one-level ∑ - i=1mkP +class="cmr-12">preconditioner. +
+

A list of the parameters that can be set, along with their allowed and default values, is ikz +class="cmr-12">given in Tables 2-8.
+

Remark 2. A smoother is usually obtained by combining two objects: ik. -

Variants of the classical AS method, which use modifications of the restriction and +class="cmr-12">a smoother (SMOOTHER_TYPE) and a local solver (SUB_SOLVE), as specified prolongation operators, are also implemented in MLD2P4. Among them, the Restricted +class="cmr-12">in Tables 7-8. For example, the block-Jacobi smoother using ILU(0) on the AS (RAS) preconditioner usually outperforms the classical AS preconditioner in terms +class="cmr-12">blocks is obtained by combining the block-Jacobi smoother object with the of convergence rate and of computation and communication time on parallel +class="cmr-12">ILU(0) solver object. Similarly, the hybrid Gauss-Seidel smoother (see Note in distributed-memory computers, and is therefore the most widely used among the AS +class="cmr-12">Table 7) is obtained by combining the block-Jacobi smoother object with a preconditioners [6]. -

Direct solvers based on sparse LU factorizations, implemented in the third-party +class="cmr-12">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 point-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 libraries reported in Sectionsmoother. +

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 3.2, can be applied as coarsest-level solvers by +href="#x17-160125">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. +

Remark 4. The argument idx can be used to allow finer control for those solvers; +for instance, by specifying the keyword MUMPS_IPAR_ENTRY and an appropriate value +for idx, it is possible to set any entry in the MUMPS integer control array. See also +Sec. 6. +

+ + + +

+ + + +
+

+

+ +

what

data type

val

default

comments

’ML_CYCLE’

character(len=*)

’VCYCLE’ +

’WCYCLE’ +

’KCYCLE’ +

’ADD’

’VCYCLE’

Multilevel cycle: V-cycle, W-cycle, K-cycle, +and additive composition.

’OUTER_SWEEPS’

integer

Any integer +

number ≥ 1

1

Number of multilevel cycles.

+
Table 2: Parameters defining the multilevel cycle and the number of cycles to be +applied.
+ + + +
+
+
+ + + +

+ + + +
+

+ + + +

+ + + + + + + +
Note. The aggregation algorithm stops when at least one of the following criteria is met: the coarse size threshold, the coarse size threshold per process, the
+
minimum 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.
+

what

data type

val

default

comments

’MIN_COARSE_SIZE_PER_PROCESS’

integer

Any number +

> 0

200

Coarse size threshold per process. The +aggregation stops if the global number of +variables of the computed coarsest matrix +is lower than or equal to this threshold +multiplied by the number of processes. +

’MIN_COARSE_SIZE’

integer

Any number +

> 0

-1

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). If negative, +it is ignored in favour of the default for +’MIN_COARSE_SIZE_PER_PROCESS’.

’MIN_CR_RATIO’

real

Any number +

> 1

1.5

Minimum coarsening +ratio. The aggregation stops if the ratio +between the global matrix dimensions at +two consecutive levels is lower than or +equal to this threshold (see Note).

’MAX_LEVS’

integer

Any integer +

number > 1

20

Maximum number of levels. The +aggregation stops if the number of levels +reaches this value (see Note).

’PAR_AGGR_ALG’

character(len=*)

’DEC’, +’SYMDEC’, +’COUPLED’

’DEC’

Parallel aggregation algorithm. +

the SYMDEC option applies decoupled +aggregation to the sparsity pattern of +A + AT .

’AGGR_TYPE’

character(len=*)

’SOC1’

’SOC1’, +’SOC2’, +’MATCHBOXP’

Type of aggregation algorithm: currently, +for the +decoupled aggregation we implement two +measures of strength of connection, the +one by Vaněk, Mandel and Brezina [29], +and the one by Gratton et al [19]. The +coupled aggregation is based on a parallel +version of the half-approximate matching +implemented in the MatchBox-P software +package AGGIUNGERE LINK AL +PACKAGE?

’AGGR_SIZE’

integer

Any integer +

number +power of 2 +and > 2

4

Maximum size of aggregates when the +coupled aggregation based on matching +is applied. For aggressive coarsening +with size of aggregate larger than 8 +we recommend the use of smoothed +prolongators. MODIFICARE +CODICE

’AGGR_PROL’

character(len=*)

’SMOOTHED’, MLD2P4. Native inexact solvers based on incomplete LU factorizations, as well as +class="cmtt-10x-x-109">’UNSMOOTHED’

’SMOOTHED’

Prolongator used by the aggregation +algorithm: smoothed or unsmoothed (i.e., +tentative prolongator).

+ + +
+
Table 3: Parameters defining the aggregation algorithm.
+ + + +
+
+
+ + + +

+ + + +
+

+

+ + +
Note. Different thresholds at different levels, such as those used in [29, Section 5.1], can be easily set by invoking the rou-
+
tine set with the parameter ilev.
+

what

data type

val

default

comments

’AGGR_ORD’

character(len=*)

’NATURAL’ +

’DEGREE’

’NATURAL’

Initial ordering of indices for +the decoupled 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,1]

0.01

The threshold θ in the decoupled +aggregation algorithm, see (??) in +Section ??. 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 (??) in Section ??).

+
Table 4: Parameters defining the aggregation algorithm (continued).
+ + + +
+
+
+ + + +

+ + + +
+

+

+ + +
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.
+

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’ +

’PCG’

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 and related Jacobi, hybrid (forward) Gauss-Seidel, and block Jacobi preconditioners are +class="cmmi-10x-x-109">ℓ1-versions; also available. Direct solvers usually lead to more effective preconditioners in +class="cmbx-10x-x-109">preconditioned Conjugate Gradient coupled terms of algorithmic scalability; however, this does not guarantee parallel +class="cmbx-10x-x-109">with the block-Jacobi preconditioner with efficiency. +class="cmbx-10x-x-109">ILU(0) on the blocks. +

Note that UMF and SLU require the coarsest matrix +to be replicated, SLUDIST, JACOBI, GS, BJAC and PCG +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 +of the solver (see Remark 3, p. 24). Note also that +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(p), ILU(p,t), MILU(p), +LU from MUMPS, SuperLU or UMFPACK +(plus triangular solve). Aggiungere Sparse +Approssimate per GPU? Note that UMFPACK +and SuperLU_Dist are available only in double +precision.

+
Table 5: Parameters defining the coarse-space correction at the coarsest level.
+
+
+
-

+ + + +
+

+

+ + +

what

data type

val

default

comments

’COARSE_SWEEPS’

integer

Any integer +

number > 0

10

Number of sweeps when JACOBI, GS or BJAC is +chosen as coarsest-level solver. Aggiungere +criterio di arresto del PCG?

’COARSE_FILLIN’

integer

Any integer +

number ≥ 0

0

Fill-in level p of the ILU factorizations.

’COARSE_ILUTHRS’

real(kind_parameter)

Any real +

number ≥ 0

0

Drop tolerance t in the ILU(p,t) +factorization.

+
Table 6: Parameters defining the coarse-space correction at the coarsest level +(continued).
+ + + +
+
+
+ + + +

+ + + +
+

+

+ + + +

what

data type

val

default

comments

’SMOOTHER_TYPE’

character(len=*)

’JACOBI’ +

’GS’ +

’BGS’ +

’BJAC’ +

’AS’

’FBGS’

Type of smoother used in the multilevel +preconditioner: point-Jacobi, hybrid +(forward) Gauss-Seidel, hybrid backward +Gauss-Seidel, block-Jacobi, ℓ1-versions? +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 +multilevel +preconditioners, +respectively +

ILU for block-Jacobi +and Additive Schwarz +one-level +preconditioners +ℓ1-versions?

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(p), ILU(p,t), MILU(p), +LU from MUMPS, SuperLU +or UMFPACK (plus triangular solve). See +Note for details on hybrid Gauss-Seidel.

’SMOOTHER_SWEEPS’

integer

Any integer +

number ≥ 0

1

Number of sweeps of the smoother or +one-level preconditioner. In the multilevel +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 ≥ 0

1

Number of overlap layers, for Additive +Schwarz only.

+
Table 7: Parameters defining the smoother or the details of the one-level +preconditioner.
+ + + +
+
+
+ + + +

+ + + +
+

+

+ + + + + + +

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

0

Fill-in level p of the incomplete LU +factorizations.

’SUB_ILUTHRS’

real(kind_parameter)

Any real +number ≥ 0

0

Drop tolerance t in the ILU(p,t) factorization.

’MUMPS_LOC_GLOB’

character(len=*)

LOCAL_SOLVER’ +

GLOBAL_SOLVER’

GLOBAL_SOLVER’

Whether MUMPS should be used as a +distributed solver, or as a serial solver acting +only on the part of the matrix local to each +process.

’MUMPS_IPAR_ENTRY’

integer

Any integer +number

0

Set an entry in the MUMPS integer control +array, as chosen via the idx optional argument.

’MUMPS_RPAR_ENTRY’

real

Any real +number

0

Set an entry in the MUMPS real control array, +as chosen via the idx optional argument.

+
Table 8: Parameters defining the smoother or the details of the one-level preconditioner +(continued).
+ + + +
+
+ + + + + + +

[next] [prev] [] [front] [up]

-

diff --git a/docs/html/userhtmlsu9.html b/docs/html/userhtmlsu9.html index b39f728c..9207ffc5 100644 --- a/docs/html/userhtmlsu9.html +++ b/docs/html/userhtmlsu9.html @@ -1,7 +1,7 @@ -Examples +Method hierarchy_build @@ -10,8 +10,17 @@ -

[next] [prev] [prev-tail] [tail] [up]

5.1 Examples

-

The code reported in Figure 2 shows how to set and apply the default multilevel -preconditioner available in the real double precision version of AMG4PSBLAS -(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 +class="cmr-12">5.3 Method hierarchy_build +

+

+

call p%hierarchy_build(a,desc_a,info)
+

+

This method builds the hierarchy of matrices and restriction/prolongation operators for with the CG solver provided by PSBLAS (the matrix of the system to be +class="cmr-12">the multilevel preconditioner p, according to the requirements made by the user solved is assumed to be positive definite). As previously observed, the modules -psb_base_mod, amg_prec_mod through the methods init 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 amg_dexample_ml.f90, in the -directory examples/fileread of the AMG4PSBLAS 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 set. +

Arguments +

+ + + + + +

a

type(psb_xspmat_type), 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 AMG4PSBLAS +under use. See the PSBLAS User’s Guide for details [16]. - - - -

The setup and application of the default multilevel 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/. -

- - - - - - - -
-

- - - -

-  use psb_base_mod
-  use amg_prec_mod
-  use psb_krylov_mod
-... ...
-!
-! sparse matrix
-  type(psb_dspmat_type) :: A
-! sparse matrix descriptor
-  type(psb_desc_type)   :: desc_A
-! preconditioner
-  type(amg_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 multilevel 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
-
-

- - -

-
Figure 2: setup and application of the default multilevel preconditioner (example 1).
-
- - - -

-

Different versions of the multilevel 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 using the Coarsening -based on Compatible Weighted Matching. It 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 -amg_dexample_ml.f90 too. DA CORREGGERE NEL CODICE ESEMPIO -3 -

Finally, Figure.

desc_a

type(psb_desc_type), intent(in).

The communication descriptor of a. See the PSBLAS User’s Guide +for details [16].

info

integer, intent(out).

Error code. If no error, 0 is returned. See Section 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 -amg_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. -

- - - - - - - -
-

-

-... ...
-! 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 3: setup of a multilevel preconditioner based on the default decoupled coarsening
-
- - - -

-

- - - - - - - -
-

-

-... ...
-! 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(’PAR_AGGR_ALG’,’COUPLED’,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 4: setup of a multilevel preconditioner based on the coupled coarsening based -on weighted matching
-
- - - -

-

+href="userhtmlse7.html#x26-300007">7 for details.
- -
-

-

-... ...
-! 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)
-
-

-
Figure 5: setup of a one-level Schwarz preconditioner.
-
- - - -

- - - - - - -

[next] [prev] [prev-tail] [front] [up]

-

diff --git a/docs/src/license.tex b/docs/src/license.tex index 1b66f66f..289ac7a2 100644 --- a/docs/src/license.tex +++ b/docs/src/license.tex @@ -2,9 +2,8 @@ \markboth{\textsc{AMG4PSBLAS User's and Reference Guide}} {\textsc{\ref{sec:license} License}} -{\bf DA CONTROLLARE E MODIFICARE INCLUDENDO I CREDITS A MLD2P4} -The AMG4PSBLAS is freely distributable under the following copyright + AMG4PSBLAS is freely distributable under the following copyright terms: {\small \begin{verbatim} @@ -44,3 +43,46 @@ terms: {\small \end{verbatim} } +\newpage + AMG4PSBLAS is an evolution of MLD2P4, whose license we reproduce here + to abide by its terms: {\small +\begin{verbatim} + + + MLD2P4 version 2.2 + MultiLevel Domain Decomposition Parallel Preconditioners Package + based on PSBLAS (Parallel Sparse BLAS version 3.5) + + (C) Copyright 2008-2018 + + Salvatore Filippone + Pasqua D'Ambra + Daniela di Serafino + + + 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. + +\end{verbatim} + } \ No newline at end of file diff --git a/docs/src/userguide.tex b/docs/src/userguide.tex index f768680e..fbae8ca6 100644 --- a/docs/src/userguide.tex +++ b/docs/src/userguide.tex @@ -89,7 +89,7 @@ \newcommand{\precdata}{\hyperlink{precdata}{{\tt mld\_prec\_type}}} \newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}} \newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}} -\newcommand{\Ref}[1]{\mbox{(\ref{#1})}} +%\newcommand{\Ref}[1]{\mbox{(\ref{#1})}} \begin{document} \pdfbookmark{AMG4PSBLAS User's and Reference Guide}{title} diff --git a/docs/src/userhtml.tex b/docs/src/userhtml.tex index 86d4cf93..8a0441b9 100644 --- a/docs/src/userhtml.tex +++ b/docs/src/userhtml.tex @@ -87,7 +87,7 @@ \newcommand{\precdata}{\hyperlink{precdata}{{\tt mld\_prec\_type}}} \newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}} \newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}} -\newcommand{\Ref}[1]{\mbox{(\ref{#1})}} +%\newcommand{\Ref}[1]{\mbox{(\ref{#1})}} \begin{document} {\LARGE\bfseries MLD2P4\\[.8ex] User's and Reference Guide}\\[\baselineskip] diff --git a/docs/src/userinterface.tex b/docs/src/userinterface.tex index 5ee33ab1..fea6848f 100644 --- a/docs/src/userinterface.tex +++ b/docs/src/userinterface.tex @@ -240,28 +240,30 @@ be applied. \bsideways \begin{center} %\begin{tabular}{|p{5cm}|l|p{2.4cm}|p{2.5cm}|p{5cm}|} -\begin{tabular}{|p{3.9cm}|l|p{2.3cm}|p{2.9cm}|p{6.9cm}|} +\begin{tabular}{|p{5.7cm}|l|p{2.3cm}|p{2.5cm}|p{6.9cm}|} \hline \verb|what| & \textsc{data type} & \verb|val| & \textsc{default} & \textsc{comments} \\ \hline -\verb|'MIN_COARSE_SIZE'| & \verb|integer| +\verb|'MIN_COARSE_SIZE_PER_PROCESS'| & \verb|integer| & Any number \par $> 0$ - & $\lfloor 40 \sqrt[3]{n} \rfloor$, where $n$ is the dimension - of the matrix at the finest level - & Coarse size threshold. The aggregation stops - if the global number of variables of the + & $200$ + & Coarse size threshold per process. The aggregation stops + if the global number of variables of the computed coarsest matrix is lower than or equal to this threshold - (see Note). + multiplied by the number of processes. + \\ \hline -\verb|'MIN_COARSE_SIZE_PROCESS'| & \verb|integer| +\verb|'MIN_COARSE_SIZE'| & \verb|integer| & Any number \par $> 0$ - & $200$ - & Coarse size threshold per process. The aggregation stops - if the number of variables of the - computed coarsest matrix on the local process + & -1 + & 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). + (see Note). If negative, it is ignored in + favour of the default for + \verb|'MIN_COARSE_SIZE_PER_PROCESS'|. \\ \hline \verb|'MIN_CR_RATIO'| & \verb|real|