<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html > <head><title>Getting Started</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="generator" content="TeX4ht (http://www.tug.org/tex4ht/)"> <meta name="originator" content="TeX4ht (http://www.tug.org/tex4ht/)"> <!-- html,3 --> <meta name="src" content="userhtml.tex"> <link rel="stylesheet" type="text/css" href="userhtml.css"> </head><body > <!--l. 1--><div class="crosslinks"><p class="noindent"><span class="cmr-12">[</span><a href="userhtmlse5.html" ><span class="cmr-12">next</span></a><span class="cmr-12">] [</span><a href="userhtmlse3.html" ><span class="cmr-12">prev</span></a><span class="cmr-12">] [</span><a href="userhtmlse3.html#tailuserhtmlse3.html" ><span class="cmr-12">prev-tail</span></a><span class="cmr-12">] [</span><a href="#tailuserhtmlse4.html"><span class="cmr-12">tail</span></a><span class="cmr-12">] [</span><a href="userhtml.html#userhtmlse4.html" ><span class="cmr-12">up</span></a><span class="cmr-12">] </span></p></div> <h3 class="sectionHead"><span class="titlemark"><span class="cmr-12">4 </span></span> <a id="x14-130004"></a><span class="cmr-12">Getting Started</span></h3> <!--l. 5--><p class="noindent" ><span class="cmr-12">This section describes the basics for building and applying AMG4PSBLAS one-level</span> <span class="cmr-12">and multilevel (i.e., AMG) preconditioners with the Krylov solvers included in</span> <span class="cmr-12">PSBLAS</span><span class="cmr-12"> </span><span class="cite"><span class="cmr-12">[</span><a href="userhtmlli5.html#XPSBLASGUIDE"><span class="cmr-12">20</span></a><span class="cmr-12">]</span></span><span class="cmr-12">.</span> <!--l. 9--><p class="indent" > <span class="cmr-12">The following steps are required:</span> <ol class="enumerate1" > <li class="enumerate" id="x14-13002x1"><span class="cmti-12">Declare the preconditioner data structure</span><span class="cmr-12">. It is a derived data type,</span> <span class="obeylines-h"><span class="verb"><span class="cmtt-12">amg_</span></span></span><span class="cmti-12">x</span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">prec_</span></span></span> <span class="obeylines-h"><span class="verb"><span class="cmtt-12">type</span></span></span><span class="cmr-12">, where </span><span class="cmti-12">x </span><span class="cmr-12">may be </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">s</span></span></span><span class="cmr-12">, </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">d</span></span></span><span class="cmr-12">, </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">c</span></span></span> <span class="cmr-12">or </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">z</span></span></span><span class="cmr-12">, according to the basic data</span> <span class="cmr-12">type of the sparse matrix (</span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">s</span></span></span> <span class="cmr-12">= real single precision; </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">d</span></span></span> <span class="cmr-12">= real double precision;</span> <span class="obeylines-h"><span class="verb"><span class="cmtt-12">c</span></span></span> <span class="cmr-12">= complex single precision; </span><span class="obeylines-h"><span class="verb"><span class="cmtt-12">z</span></span></span> <span class="cmr-12">= complex double precision). This data</span> <span class="cmr-12">structure is accessed by the user only through the AMG4PSBLAS routines,</span> <span class="cmr-12">following an object-oriented approach.</span> </li> <li class="enumerate" id="x14-13004x2"><span class="cmti-12">Allocate and initialize the preconditioner data structure, according to a</span> <span class="cmti-12">preconditioner type chosen by the user</span><span class="cmr-12">. This is performed by the routine</span> <span class="lstinline"></span><span class="cmtt-12">init</span><span class="cmr-12">, which also sets defaults for each preconditioner type selected by</span> <span class="cmr-12">the user. The preconditioner types and the defaults associated with them</span> <span class="cmr-12">are given in Table</span><span class="cmr-12"> </span><a href="#x14-13015r1"><span class="cmr-12">1</span><!--tex4ht:ref: tab:precinit --></a><span class="cmr-12">, where the strings used by </span><span class="lstinline"></span><span class="cmtt-12">init</span> <span class="cmr-12">to identify the</span> <span class="cmr-12">preconditioner types are also given. Note that these strings are valid also if</span> <span class="cmr-12">uppercase letters are substituted by corresponding lowercase ones.</span> </li> <li class="enumerate" id="x14-13006x3"><span class="cmti-12">Modify the selected preconditioner type, by properly setting preconditioner</span> <span class="cmti-12">parameters. </span><span class="cmr-12">This is performed by the routine </span><span class="lstinline"></span><span class="cmtt-12">set</span><span class="cmr-12">. This routine must be</span> <span class="cmr-12">called if the user wants to modify the default values of the parameters</span> <span class="cmr-12">associated with the selected preconditioner type, to obtain a variant of that</span> <span class="cmr-12">preconditioner. Examples of use of </span><span class="lstinline"></span><span class="cmtt-12">set</span> <span class="cmr-12">are given in Section</span><span class="cmr-12"> </span><a href="userhtmlsu6.html#x15-140004.1"><span class="cmr-12">4.1</span><!--tex4ht:ref: sec:examples --></a><span class="cmr-12">; a complete</span> <span class="cmr-12">list of all the preconditioner parameters and their allowed and default values</span> <span class="cmr-12">is provided in Section</span><span class="cmr-12"> </span><a href="userhtmlse5.html#x17-160005"><span class="cmr-12">5</span><!--tex4ht:ref: sec:userinterface --></a><span class="cmr-12">, Tables</span><span class="cmr-12"> </span><a href="userhtmlsu9.html#x19-18009r2"><span class="cmr-12">2</span><!--tex4ht:ref: tab:p_cycle --></a><span class="cmr-12">-</span><a href="userhtmlsu9.html#x19-18015r8"><span class="cmr-12">8</span><!--tex4ht:ref: tab:p_smoother_1 --></a><span class="cmr-12">.</span> </li> <li class="enumerate" id="x14-13008x4"><span class="cmti-12">Build the preconditioner for a given matrix</span><span class="cmr-12">. If the selected preconditioner is</span> <span class="cmr-12">multilevel, then two steps must be performed, as specified next.</span> <ol class="enumerate2" > <li class="enumerate" id="x14-13009x0"><span class="cmti-12">Build the AMG hierarchy for a given matrix. </span><span class="cmr-12">This is performed by the</span> <span class="cmr-12">routine </span><span class="lstinline"></span><span class="cmtt-12">hierarchy_build</span><span class="cmr-12">.</span> </li> <li class="enumerate" id="x14-13010x0"><span class="cmti-12">Build the preconditioner for a given matrix. </span><span class="cmr-12">This is performed by the</span> <span class="cmr-12">routine </span><span class="lstinline"></span><span class="cmtt-12">smoothers_build</span><span class="cmr-12">.</span></li></ol> <!--l. 48--><p class="noindent" ><span class="cmr-12">If the selected preconditioner is one-level, it is built in a single step, performed by</span> <span class="cmr-12">the routine </span><span class="lstinline"></span><span class="cmtt-12">bld</span><span class="cmr-12">.</span> </li> <li class="enumerate" id="x14-13012x5"><span class="cmti-12">Apply the preconditioner at each iteration of a Krylov solver. </span><span class="cmr-12">This is performed by</span> <span class="cmr-12">the method </span><span class="lstinline"></span><span class="cmtt-12">apply</span><span class="cmr-12">. When using the PSBLAS Krylov solvers, this step is</span> <span class="cmr-12">completely transparent to the user, since </span><span class="lstinline"></span><span class="cmtt-12">apply</span> <span class="cmr-12">is called by the PSBLAS routine</span> <span class="cmr-12">implementing the Krylov solver (</span><span class="lstinline"></span><span class="cmtt-12">psb_krylov</span><span class="cmr-12">).</span> </li> <li class="enumerate" id="x14-13014x6"><span class="cmti-12">Free the preconditioner data structure</span><span class="cmr-12">. This is performed by the routine </span><span class="lstinline"></span><span class="cmtt-12">free</span><span class="cmr-12">.</span> <span class="cmr-12">This step is complementary to step 1 and should be performed when the</span> <span class="cmr-12">preconditioner is no more used.</span></li></ol> <!--l. 59--><p class="indent" > <span class="cmr-12">All the previous routines are available as methods of the preconditioner object. A</span> <span class="cmr-12">detailed description of them is given in Section</span><span class="cmr-12"> </span><a href="userhtmlse5.html#x17-160005"><span class="cmr-12">5</span><!--tex4ht:ref: sec:userinterface --></a><span class="cmr-12">. Examples showing the basic use of</span> <span class="cmr-12">AMG4PSBLAS are reported in Section</span><span class="cmr-12"> </span><a href="userhtmlsu6.html#x15-140004.1"><span class="cmr-12">4.1</span><!--tex4ht:ref: sec:examples --></a><span class="cmr-12">.</span> <div class="table"> <!--l. 63--><p class="indent" > <a id="x14-13015r1"></a><hr class="float"><div class="float" > <div class="center" > <!--l. 64--><p class="noindent" > <div class="tabular"> <table id="TBL-1" class="tabular" cellspacing="0" cellpadding="0" ><colgroup id="TBL-1-1g"><col id="TBL-1-1"></colgroup><colgroup id="TBL-1-2g"><col id="TBL-1-2"></colgroup><colgroup id="TBL-1-3g"><col id="TBL-1-3"></colgroup><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-1-1" class="td11"><span class="cmcsc-10x-x-109"><span class="small-caps">t</span><span class="small-caps">y</span><span class="small-caps">p</span><span class="small-caps">e</span> </span></td><td style="white-space:wrap; text-align:left;" id="TBL-1-1-2" class="td11"><!--l. 68--><p class="noindent" ><span class="cmcsc-10x-x-109"><span class="small-caps">s</span><span class="small-caps">t</span><span class="small-caps">r</span><span class="small-caps">i</span><span class="small-caps">n</span><span class="small-caps">g</span></span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-1-3" class="td11"><!--l. 68--><p class="noindent" ><span class="cmcsc-10x-x-109"><span class="small-caps">d</span><span class="small-caps">e</span><span class="small-caps">f</span><span class="small-caps">a</span><span class="small-caps">u</span><span class="small-caps">l</span><span class="small-caps">t</span> <span class="small-caps">p</span><span class="small-caps">r</span><span class="small-caps">e</span><span class="small-caps">c</span><span class="small-caps">o</span><span class="small-caps">n</span><span class="small-caps">d</span><span class="small-caps">i</span><span class="small-caps">t</span><span class="small-caps">i</span><span class="small-caps">o</span><span class="small-caps">n</span><span class="small-caps">e</span><span class="small-caps">r</span></span> </td></tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-2-1" class="td11">No preconditioner </td><td style="white-space:wrap; text-align:left;" id="TBL-1-2-2" class="td11"><!--l. 69--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">NONE</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-2-3" class="td11"><!--l. 69--><p class="noindent" >Considered to use the PSBLAS Krylov solvers with no preconditioner. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-3-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-3-1" class="td11">Diagonal </td><td style="white-space:wrap; text-align:left;" id="TBL-1-3-2" class="td11"><!--l. 71--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">DIAG</span><span class="cmtt-10x-x-109">’</span>, <span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">JACOBI</span><span class="cmtt-10x-x-109">’</span>, <span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">L1</span><span class="cmtt-10x-x-109">-</span><span class="cmtt-10x-x-109">JACOBI</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-3-3" class="td11"><!--l. 71--><p class="noindent" >Diagonal preconditioner. For any zero diagonal entry of the matrix to be preconditioned, the corresponding entry of the preconditioner is set to 1. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-4-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-4-1" class="td11">Gauss-Seidel </td><td style="white-space:wrap; text-align:left;" id="TBL-1-4-2" class="td11"><!--l. 74--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">GS</span><span class="cmtt-10x-x-109">’</span>, <span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">L1</span><span class="cmtt-10x-x-109">-</span><span class="cmtt-10x-x-109">GS</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-4-3" class="td11"><!--l. 74--><p class="noindent" >Hybrid Gauss-Seidel (forward), that is, global block Jacobi with Gauss-Seidel as local solver. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-5-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-5-1" class="td11">Symmetrized Gauss-Seidel</td><td style="white-space:wrap; text-align:left;" id="TBL-1-5-2" class="td11"><!--l. 77--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">FBGS</span><span class="cmtt-10x-x-109">’</span>, <span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">L1</span><span class="cmtt-10x-x-109">-</span><span class="cmtt-10x-x-109">FBGS</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-5-3" class="td11"><!--l. 77--><p class="noindent" >Symmetrized hybrid Gauss-Seidel, that is, forward Gauss-Seidel followed by backward Gauss-Seidel. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-6-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-6-1" class="td11">Block Jacobi </td><td style="white-space:wrap; text-align:left;" id="TBL-1-6-2" class="td11"><!--l. 80--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">BJAC</span><span class="cmtt-10x-x-109">’</span>, <span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">L1</span><span class="cmtt-10x-x-109">-</span><span class="cmtt-10x-x-109">BJAC</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-6-3" class="td11"><!--l. 80--><p class="noindent" >Block-Jacobi with ILU(0) on the local blocks. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-7-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-7-1" class="td11">Additive Schwarz </td><td style="white-space:wrap; text-align:left;" id="TBL-1-7-2" class="td11"><!--l. 81--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">AS</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-7-3" class="td11"><!--l. 81--><p class="noindent" >Additive Schwarz (AS), with overlap 1 and ILU(0) on the local blocks. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-8-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-8-1" class="td11">Multilevel </td><td style="white-space:wrap; text-align:left;" id="TBL-1-8-2" class="td11"><!--l. 83--><p class="noindent" ><span class="lstinline"></span><span class="cmtt-10x-x-109">’</span><span class="cmtt-10x-x-109">ML</span><span class="cmtt-10x-x-109">’</span> </td><td style="white-space:wrap; text-align:left;" id="TBL-1-8-3" class="td11"><!--l. 83--><p class="noindent" >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 <a href="userhtmlsu9.html#x19-18009r2">2<!--tex4ht:ref: tab:p_cycle --></a>-<a href="userhtmlsu9.html#x19-18015r8">8<!--tex4ht:ref: tab:p_smoother_1 --></a> for further details of the preconditioner. </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-1-9-"><td style="white-space:nowrap; text-align:left;" id="TBL-1-9-1" class="td11"> </td></tr></table></div> <br /> <div class="caption" ><span class="id">Table 1: </span><span class="content">Preconditioner types, corresponding strings and default choices. </span></div><!--tex4ht:label?: x14-13015r1 --> </div> </div><hr class="endfloat" /> </div> <!--l. 98--><p class="indent" > <span class="cmr-12">Note that the module </span><span class="lstinline"></span><span class="cmtt-12">amg_prec_mod</span><span class="cmr-12">, containing the definition of the preconditioner</span> <span class="cmr-12">data type and the interfaces to the routines of AMG4PSBLAS, must be used</span> <span class="cmr-12">in any program calling such routines. The modules </span><span class="lstinline"></span><span class="cmtt-12">psb_base_mod</span><span class="cmr-12">, for the</span> <span class="cmr-12">sparse matrix and communication descriptor data types, and </span><span class="lstinline"></span><span class="cmtt-12">psb_krylov_mod</span><span class="cmr-12">,</span> <span class="cmr-12">for interfacing with the Krylov solvers, must be also used (see Section</span><span class="cmr-12"> </span><a href="userhtmlsu6.html#x15-140004.1"><span class="cmr-12">4.1</span><!--tex4ht:ref: sec:examples --></a><span class="cmr-12">).</span> <br class="newline" /> <!--l. 105--><p class="indent" > <span class="cmbx-12">Remark 1. </span><span class="cmr-12">Coarsest-level solvers based on the LU factorization, such as those</span> <span class="cmr-12">implemented in UMFPACK, MUMPS, SuperLU, and SuperLU</span><span class="cmr-12">_Dist, usually lead to</span> <span class="cmr-12">smaller numbers of preconditioned Krylov iterations than inexact solvers, when the</span> <span class="cmr-12">linear system comes from a standard discretization of basic scalar elliptic PDE</span> <span class="cmr-12">problems. However, this does not necessarily correspond to the shortest execution time</span> <span class="cmr-12">on parallel</span><span class="cmr-12"> computers.</span> <div class="subsectionTOCS"> <span class="cmr-12"> </span><span class="subsectionToc" ><span class="cmr-12">4.1 </span><a href="userhtmlsu6.html#x15-140004.1"><span class="cmr-12">Examples</span></a></span> <br /> <span class="cmr-12"> </span><span class="subsectionToc" ><span class="cmr-12">4.2 </span><a href="userhtmlsu7.html#x16-150004.2"><span class="cmr-12">GPU example</span></a></span> </div> <!--l. 1--><div class="crosslinks"><p class="noindent"><span class="cmr-12">[</span><a href="userhtmlse5.html" ><span class="cmr-12">next</span></a><span class="cmr-12">] [</span><a href="userhtmlse3.html" ><span class="cmr-12">prev</span></a><span class="cmr-12">] [</span><a href="userhtmlse3.html#tailuserhtmlse3.html" ><span class="cmr-12">prev-tail</span></a><span class="cmr-12">] [</span><a href="userhtmlse4.html" ><span class="cmr-12">front</span></a><span class="cmr-12">] [</span><a href="userhtml.html#userhtmlse4.html" ><span class="cmr-12">up</span></a><span class="cmr-12">] </span></p></div> <!--l. 1--><p class="indent" > <a id="tailuserhtmlse4.html"></a> </body></html>