fdurastante/amg4psblas
1
0
Fork 0
mirror of https://github.com/sfilippone/amg4psblas.git synced 2026-10-06 22:55:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fixed doc copyright vs contribution

Browse Source
This commit is contained in:
Salvatore Filippone
2017-08-09 14:31:44 +01:00
parent 93c16477b2
commit 8ecc4d7200
35 changed files with 4966 additions and 4908 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/html/node15.html
+219 -155
View File
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Getting Started</TITLE>
<META NAME="description" CONTENT="Getting Started">
<TITLE>Smoothers and coarsest-level solvers</TITLE>
<META NAME="description" CONTENT="Smoothers and coarsest-level solvers">
<META NAME="keywords" CONTENT="userhtml">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
@@ -18,9 +18,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
<LINK REL="STYLESHEET" HREF="userhtml.css">
<LINK REL="next" HREF="node17.html">
<LINK REL="previous" HREF="node11.html">
<LINK REL="up" HREF="userhtml.html">
<LINK REL="previous" HREF="node14.html">
<LINK REL="up" HREF="node12.html">
<LINK REL="next" HREF="node16.html">
</HEAD>
@@ -30,9 +29,9 @@ original version by: Nikos Drakos, CBLU, University of Leeds
HREF="node16.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html259"
HREF="userhtml.html">
HREF="node12.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html253"
<A NAME="tex2html255"
HREF="node14.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html261"
@@ -40,171 +39,236 @@ original version by: Nikos Drakos, CBLU, University of Leeds
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html264"
HREF="node16.html">Examples</A>
HREF="node16.html">Getting Started</A>
<B> Up:</B> <A NAME="tex2html260"
HREF="userhtml.html">userhtml</A>
<B> Previous:</B> <A NAME="tex2html254"
HREF="node14.html">Smoothers and coarsest-level solvers</A>
HREF="node12.html">Multigrid Background</A>
<B> Previous:</B> <A NAME="tex2html256"
HREF="node14.html">Smoothed Aggregation</A>
&nbsp; <B> <A NAME="tex2html262"
HREF="node2.html">Contents</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION00070000000000000000"></A><A NAME="sec:started"></A>
<H2><A NAME="SECTION00063000000000000000"></A><A NAME="sec:smoothers"></A>
<BR>
Getting Started
</H1><FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
Smoothers and coarsest-level solvers
</H2><FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">We describe the basics for building and applying MLD2P4 one-level and multi-level
(i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS [<A
HREF="node29.html#PSBLASGUIDE">13</A>].
The following steps are required:
</FONT></FONT></FONT>
<OL>
<LI><I>Declare the preconditioner data structure</I>. It is a derived data type,
<code>mld_</code><I>x</I><code>prec_</code> <code>type</code>, where <I>x</I> may be <code>s</code>, <code>d</code>, <code>c</code>
or <code>z</code>, according to the basic data type of the sparse matrix
(<code>s</code> = real single precision; <code>d</code> = real double precision;
<code>c</code> = complex single precision; <code>z</code> = complex double precision).
This data structure is accessed by the user only through the MLD2P4 routines,
following an object-oriented approach.
</LI>
<LI><I>Allocate and initialize the preconditioner data structure, according to
a preconditioner type chosen by the user</I>. This is performed by the routine
<code>init</code>, 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&nbsp;<A HREF="#tab:precinit">1</A>, where the strings used by
<code>init</code> to identify the preconditioner types are also given.
Note that these strings are valid also if uppercase letters are substituted by
corresponding lowercase ones.
</LI>
<LI><I>Modify the selected preconditioner type, by properly setting
preconditioner parameters.</I> This is performed by the routine <code>set</code>.
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 <code>set</code> are given in
Section&nbsp;<A HREF="node16.html#sec:examples">5.1</A>; a complete list of all the
preconditioner parameters and their allowed and default values is provided in
Section&nbsp;<A HREF="node17.html#sec:userinterface">6</A>, Tables&nbsp;<A HREF="#tab:p_cycle">2</A>-<A HREF="#tab:p_smoother_1">8</A>.
</LI>
<LI><I>Build the preconditioner for a given matrix</I>. If the selected preconditioner
is multi-level, then two steps must be performed, as specified next.
<DL COMPACT>
<DT>4.1</DT>
<DD><I>Build the aggregation hierarchy for a given matrix.</I> This is
performed by the routine <code>hierarchy_build</code>.
</DD>
<DT>4.2</DT>
<DD><I>Build the preconditioner for a given matrix.</I> This is performed
by the routine <code>smoothers_build</code>.
</DD>
</DL>
If the selected preconditioner is one-level, it is built in a single step,
performed by the routine <code>bld</code>.
</LI>
<LI><I>Apply the preconditioner at each iteration of a Krylov solver.</I>
This is performed by the routine <code>aply</code>. When using the PSBLAS Krylov solvers,
this step is completely transparent to the user, since <code>aply</code> is called
by the PSBLAS routine implementing the Krylov solver (<code>psb_krylov</code>).
</LI>
<LI><I>Free the preconditioner data structure</I>. This is performed by
the routine <code>free</code>. This step is complementary to step 1 and should
be performed when the preconditioner is no more used.
</LI>
</OL><FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">All the previous routines are available as methods of the preconditioner object.
A detailed description of them is given in Section&nbsp;<A HREF="node17.html#sec:userinterface">6</A>.
Examples showing the basic use of MLD2P4 are reported in Section&nbsp;<A HREF="node16.html#sec:examples">5.1</A>.
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">The smoothers implemented in MLD2P4 include the Jacobi and block-Jacobi methods,
a hybrid version of the forward and backward Gauss-Seidel methods, and the
additive Schwarz (AS) ones (see, e.g., [<A
HREF="node30.html#Saad_book">20</A>,<A
HREF="node30.html#dd2_96">21</A>]).
</FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">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.
</FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">In the AS methods, the index space <IMG
WIDTH="25" HEIGHT="18" ALIGN="BOTTOM" BORDER="0"
SRC="img9.png"
ALT="$\Omega^k$"> is divided into <IMG
WIDTH="28" HEIGHT="31" ALIGN="MIDDLE" BORDER="0"
SRC="img50.png"
ALT="$m_k$">
subsets <IMG
WIDTH="25" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img51.png"
ALT="$\Omega^k_i$"> of size <IMG
WIDTH="32" HEIGHT="31" ALIGN="MIDDLE" BORDER="0"
SRC="img52.png"
ALT="$n_{k,i}$">, possibly
overlapping. For each <IMG
WIDTH="11" HEIGHT="18" ALIGN="BOTTOM" BORDER="0"
SRC="img30.png"
ALT="$i$"> we consider the restriction
operator <!-- MATH
$R_i^k \in \mathbb{R}^{n_{k,i} \times n_k}$
-->
<IMG
WIDTH="110" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img53.png"
ALT="$R_i^k \in \mathbb{R}^{n_{k,i} \times n_k}$">
that maps a vector <IMG
WIDTH="23" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
SRC="img54.png"
ALT="$x^k$"> to the vector <IMG
WIDTH="22" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img55.png"
ALT="$x_i^k$"> made of the components of <IMG
WIDTH="23" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
SRC="img54.png"
ALT="$x^k$">
with indices in <IMG
WIDTH="25" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img51.png"
ALT="$\Omega^k_i$">, and the prolongation operator
<!-- MATH
$P^k_i = (R_i^k)^T$
-->
<IMG
WIDTH="95" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img56.png"
ALT="$P^k_i = (R_i^k)^T$">. These operators are then used to build
<!-- MATH
$A_i^k=R_i^kA^kP_i^k$
-->
<IMG
WIDTH="113" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img57.png"
ALT="$A_i^k=R_i^kA^kP_i^k$">, which is the restriction of <IMG
WIDTH="26" HEIGHT="18" ALIGN="BOTTOM" BORDER="0"
SRC="img41.png"
ALT="$A^k$"> to the index
space <IMG
WIDTH="25" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img51.png"
ALT="$\Omega^k_i$">.
The classical AS preconditioner <IMG
WIDTH="41" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img58.png"
ALT="$M^k_{AS}$"> is defined as
</FONT></FONT></FONT>
<BR><P></P>
<DIV ALIGN="CENTER"><A NAME="897"></A>
<TABLE>
<CAPTION><STRONG>Table 1:</STRONG>
Preconditioner types, corresponding strings and default choices.
</CAPTION>
<TR><TD>
<DIV ALIGN="CENTER">
<TABLE CELLPADDING=3 BORDER="1" ALIGN="CENTER">
<TR><TD ALIGN="LEFT"><SMALL>TYPE</SMALL></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><SMALL>STRING</SMALL></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232><SMALL>DEFAULT PRECONDITIONER</SMALL></TD>
</TR>
<TR><TD ALIGN="LEFT">No preconditioner</TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><code>'NOPREC'</code></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232>Considered only to use the PSBLAS
Krylov solvers with no preconditioner.</TD>
</TR>
<TR><TD ALIGN="LEFT">Diagonal</TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><code>'DIAG'</code> or <code>'JACOBI'</code></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232>Diagonal preconditioner.
For any zero diagonal entry of the matrix to be preconditioned,
the corresponding entry of the preconditioner is set to&nbsp;1.</TD>
</TR>
<TR><TD ALIGN="LEFT">Block Jacobi</TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><code>'BJAC'</code></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232>Block-Jacobi with ILU(0) on the local blocks.</TD>
</TR>
<TR><TD ALIGN="LEFT">Additive Schwarz</TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><code>'AS'</code></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232>Restricted Additive Schwarz (RAS),
with overlap&nbsp;1 and ILU(0) on the local blocks.</TD>
</TR>
<TR><TD ALIGN="LEFT">Multilevel</TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=51><code>'ML'</code></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=232>V-cycle with one hybrid forward Gauss-Seidel
(GS) sweep as pre-smoother and one hybrid backward
GS sweep as post-smoother, basic smoothed aggregation
as coarsening algorithm, and LU (plus triangular solve)
as coarsest-level solver. See the default values in
Tables&nbsp;<A HREF="#tab:p_cycle">2</A>-<A HREF="#tab:p_smoother_1">8</A>
for further details of the preconditioner.</TD>
</TR>
</TABLE>
</DIV></TD></TR>
</TABLE>
</DIV><P></P>
<BR><FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">Note that the module <code>mld_prec_mod</code>, containing the definition of the
preconditioner data type and the interfaces to the routines of MLD2P4,
must be used in any program calling such routines.
The modules <code>psb_base_mod</code>, for the sparse matrix and communication descriptor
data types, and <code>psb_krylov_mod</code>, for interfacing with the
Krylov solvers, must be also used (see Section&nbsp;<A HREF="node16.html#sec:examples">5.1</A>).
<BR></FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1"><B>Remark 1.</B> Coarsest-level solvers based on the LU factorization,
such as those implemented in UMFPACK, MUMPS, SuperLU, and SuperLU_Dist,
usually lead to smaller numbers of preconditioned Krylov
iterations than inexact solvers, when the linear system comes from
a standard discretization of basic scalar elliptic PDE problems. However,
this does not necessarily correspond to the smallest execution time
on parallel computers. </FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT>
<BR><HR>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<!-- MATH
\begin{displaymath}
( M^k_{AS} )^{-1} = \sum_{i=1}^{m_k} P_i^k (A_i^k)^{-1} R_i^{k},
\end{displaymath}
-->
<IMG
WIDTH="219" HEIGHT="59" BORDER="0"
SRC="img59.png"
ALT="\begin{displaymath}␍ ( M^k_{AS} )^{-1} = \sum_{i=1}^{m_k} P_i^k (A_i^k)^{-1} R_i^{k},␍\end{displaymath}">
</DIV>
<BR CLEAR="ALL">
<P></P><FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">
where <IMG
WIDTH="26" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img60.png"
ALT="$A_i^k$"> is supposed to be nonsingular. We observe that an approximate
inverse of <IMG
WIDTH="26" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img60.png"
ALT="$A_i^k$"> is usually considered instead of <IMG
WIDTH="57" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img61.png"
ALT="$(A_i^k)^{-1}$">.
The setup of <IMG
WIDTH="41" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img58.png"
ALT="$M^k_{AS}$"> during the multilevel build phase
involves
</FONT></FONT></FONT>
<UL>
<LI><A NAME="tex2html265"
HREF="node16.html">Examples</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<LI>the definition of the index subspaces <IMG
WIDTH="25" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img62.png"
ALT="$\Omega_i^k$"> and of the corresponding
operators <IMG
WIDTH="26" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img63.png"
ALT="$R_i^k$"> (and <IMG
WIDTH="26" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img64.png"
ALT="$P_i^k$">);
</LI>
<LI>the computation of the submatrices <IMG
WIDTH="26" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img60.png"
ALT="$A_i^k$">;
</LI>
<LI>the computation of their inverses (usually approximated
through some form of incomplete factorization).
</LI>
</UL><FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">
The computation of <!-- MATH
$z^k=M^k_{AS}w^k$
-->
<IMG
WIDTH="102" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img65.png"
ALT="$z^k=M^k_{AS}w^k$">, with <!-- MATH
$w^k \in \mathbb{R}^{n_k}$
-->
<IMG
WIDTH="76" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img66.png"
ALT="$w^k \in \mathbb{R}^{n_k}$">, during the
multilevel application phase, requires
</FONT></FONT></FONT>
<UL>
<LI>the restriction of <IMG
WIDTH="25" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
SRC="img67.png"
ALT="$w^k$"> to the subspaces <!-- MATH
$\mathbb{R}^{n_{k,i}}$
-->
<IMG
WIDTH="41" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
SRC="img68.png"
ALT="$\mathbb{R}^{n_{k,i}}$">,
i.e. <!-- MATH
$w_i^k = R_i^{k} w^k$
-->
<IMG
WIDTH="91" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img69.png"
ALT="$w_i^k = R_i^{k} w^k$">;
</LI>
<LI>the computation of the vectors <!-- MATH
$z_i^k=(A_i^k)^{-1} w_i^k$
-->
<IMG
WIDTH="119" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img70.png"
ALT="$z_i^k=(A_i^k)^{-1} w_i^k$">;
</LI>
<LI>the prolongation and the sum of the previous vectors,
i.e. <!-- MATH
$z^k = \sum_{i=1}^{m_k} P_i^k z_i^k$
-->
<IMG
WIDTH="127" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
SRC="img71.png"
ALT="$z^k = \sum_{i=1}^{m_k} P_i^k z_i^k$">.
</LI>
</UL><FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">
Variants of the classical AS method, which use modifications of the
restriction and prolongation operators, are also implemented in MLD2P4.
Among them, the Restricted AS (RAS) preconditioner usually
outperforms the classical AS preconditioner in terms of convergence
rate and of computation and communication time on parallel distributed-memory
computers, and is therefore the most widely used among the AS
preconditioners&nbsp;[<A
HREF="node30.html#CAI_SARKIS">6</A>].
</FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1">Direct solvers based on sparse LU factorizations, implemented in the
third-party libraries reported in Section&nbsp;<A HREF="node8.html#sec:third-party">3.2</A>, can be applied
as coarsest-level solvers by MLD2P4. Native inexact solvers based on
incomplete LU factorizations, as well as Jacobi, hybrid (forward) Gauss-Seidel,
and block Jacobi preconditioners are also available. Direct solvers usually
lead to more effective preconditioners in terms of algorithmic scalability;
however, this does not guarantee parallel efficiency.
</FONT></FONT></FONT>
<P>
<FONT SIZE="+1"><FONT SIZE="+1"><FONT SIZE="+1"></FONT></FONT></FONT><HR>
<!--Navigation Panel-->
<A NAME="tex2html263"
HREF="node16.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html259"
HREF="userhtml.html">
HREF="node12.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html253"
<A NAME="tex2html255"
HREF="node14.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html261"
@@ -212,11 +276,11 @@ on parallel computers. </FONT></FONT></FONT>
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html264"
HREF="node16.html">Examples</A>
HREF="node16.html">Getting Started</A>
<B> Up:</B> <A NAME="tex2html260"
HREF="userhtml.html">userhtml</A>
<B> Previous:</B> <A NAME="tex2html254"
HREF="node14.html">Smoothers and coarsest-level solvers</A>
HREF="node12.html">Multigrid Background</A>
<B> Previous:</B> <A NAME="tex2html256"
HREF="node14.html">Smoothed Aggregation</A>
&nbsp; <B> <A NAME="tex2html262"
HREF="node2.html">Contents</A></B>
<!--End of Navigation Panel-->