mld2p4:

html/index.html html/node1.html html/node10.html html/node11.html html/node12.html html/node13.html html/node14.html html/node15.html html/node16.html html/node17.html html/node18.html html/node19.html html/node2.html html/node20.html html/node21.html html/node22.html html/node23.html html/node24.html html/node25.html html/node26.html html/node3.html html/node4.html html/node5.html html/node6.html html/node7.html html/node8.html html/node9.html html/userhtml.html src/Makefile src/building.tex src/userguide.tex src/userhtml.tex userguide.pdf Fixed mail hyperlink.
2026-10-06 22:55:12 +00:00 · 2008-07-24 13:00:39 +00:00
parent 7829b23b6a
commit 2a2601c1ee
33 changed files with 4592 additions and 4544 deletions
@@ -7,8 +7,8 @@ original version by:  Nikos Drakos, CBLU, University of Leeds
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
 <HTML>
 <HEAD>
-<TITLE>User Interface</TITLE>
-<META NAME="description" CONTENT="User Interface">
+<TITLE>Examples</TITLE>
+<META NAME="description" CONTENT="Examples">
 <META NAME="keywords" CONTENT="userhtml">
 <META NAME="resource-type" CONTENT="document">
 <META NAME="distribution" CONTENT="global">
@@ -18,147 +18,309 @@ original version by:  Nikos Drakos, CBLU, University of Leeds

 <LINK REL="STYLESHEET" HREF="userhtml.css">

-<LINK REL="next" HREF="node22.html">
-<LINK REL="previous" HREF="node13.html">
-<LINK REL="up" HREF="userhtml.html">
+<LINK REL="previous" HREF="node14.html">
+<LINK REL="up" HREF="node14.html">
 <LINK REL="next" HREF="node16.html">
 </HEAD>

 <BODY >
 <!--Navigation Panel-->
-<A NAME="tex2html239"
+<A NAME="tex2html242"
  HREF="node16.html">
 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="file:/usr/share/latex2html/icons/next.png"></A> 
-<A NAME="tex2html235"
-  HREF="userhtml.html">
+<A NAME="tex2html238"
+  HREF="node14.html">
 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="file:/usr/share/latex2html/icons/up.png"></A> 
-<A NAME="tex2html229"
+<A NAME="tex2html234"
  HREF="node14.html">
 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="file:/usr/share/latex2html/icons/prev.png"></A> 
-<A NAME="tex2html237"
+<A NAME="tex2html240"
  HREF="node2.html">
 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents"
 SRC="file:/usr/share/latex2html/icons/contents.png"></A>  
 <BR>
-<B> Next:</B> <A NAME="tex2html240"
-  HREF="node16.html">Subroutine mld_precinit</A>
-<B> Up:</B> <A NAME="tex2html236"
-  HREF="userhtml.html">userhtml</A>
-<B> Previous:</B> <A NAME="tex2html230"
-  HREF="node14.html">Examples</A>
- &nbsp; <B>  <A NAME="tex2html238"
+<B> Next:</B> <A NAME="tex2html243"
+  HREF="node16.html">User Interface</A>
+<B> Up:</B> <A NAME="tex2html239"
+  HREF="node14.html">Getting Started</A>
+<B> Previous:</B> <A NAME="tex2html235"
+  HREF="node14.html">Getting Started</A>
+ &nbsp; <B>  <A NAME="tex2html241"
  HREF="node2.html">Contents</A></B> 
 <BR>
 <BR>
 <!--End of Navigation Panel-->

-<H1><A NAME="SECTION00080000000000000000"></A><A NAME="sec:userinterface"></A>
+<H2><A NAME="SECTION00071000000000000000"></A><A NAME="sec:examples"></A>
 <BR>
-User Interface
-</H1>
+Examples
+</H2>

 <P>
-The basic user interface of MLD2P4 consists of six routines. The four routines <code>mld_</code> <code>precinit</code>,
-<code>mld_precset</code>, <code>mld_precbld</code> and <code>mld_precaply</code> encapsulate all the functionalities
-for the setup and the application of any one-level and multi-level
-preconditioner implemented in the package.
-The routine <code>mld_precfree</code> deallocates the preconditioner data structure, while
-<code>mld_precdescr</code> prints a description of the preconditioner setup by the user.
+The code reported in Figure&nbsp;<A HREF="#fig:ex_default">2</A> shows how to set and apply the default
+multi-level preconditioner available in the real double precision version
+of MLD2P4 (see Table&nbsp;<A HREF="#tab:precinit">1</A>). This preconditioner is chosen
+by simply specifying <code>'ML'</code> as second argument of <code>mld_precinit</code>
+(a call to <code>mld_precset</code> is not needed) and is applied with the BiCGSTAB
+solver provided by PSBLAS. As previously observed, the modules <code>psb_base_mod</code>,
+<code>mld_prec_mod</code> and <code>psb_krylov_mod</code> must be used by the example program.

 <P>
-For each routine, the same user interface is overloaded with
-respect to the real/complex case and the single/double precision;
-arguments with appropriate data types must be passed to the routine,
-i.e.
+The 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 <code>mld_dexample_ml.f90</code>,
+in the directory <code>examples/fileread</code> of the MLD2P4 tree (see
+Section&nbsp;<A HREF="node10.html#sec:ex_and_test">3.5</A>).
+For details on the use of the PSBLAS routines, see the PSBLAS User's
+Guide [<A
+ HREF="node25.html#PSBLASGUIDE">14</A>].

-<UL>
-<LI>the sparse matrix data structure, containing the matrix to be
-  preconditioned, must be of type <code>mld_</code><I>x</I><code>spmat_type</code>
-	with <I>x</I> = <code>s</code> for real single precision, <I>x</I> = <code>d</code>
-	for real double precision, <I>x</I> = <code>c</code> for complex single precision,
-	<I>x</I> = <code>z</code> for complex double precision;
-</LI>
-<LI>the preconditioner data structure must be of type
-  <code>mld_</code><I>x</I><code>prec_type</code>, with <I>x</I> =    
-  <code>s</code>, <code>d</code>, <code>c</code>, <code>z</code>, according to the sparse
-  matrix data structure;
-</LI>
-<LI>the arrays containing the vectors <IMG
- WIDTH="13" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
- SRC="img21.png"
- ALT="$v$"> and <IMG
- WIDTH="17" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
- SRC="img87.png"
- ALT="$w$"> involved in
-  the preconditioner application <IMG
- WIDTH="87" HEIGHT="21" ALIGN="BOTTOM" BORDER="0"
- SRC="img60.png"
- ALT="$w=M^{-1}v$"> must be of type   
-  <I>type</I><code>(</code><I>kind_parameter</I><code>)</code>, with <I>type</I> =
-  <code>real</code>, <code>complex</code> and <I>kind_parameter</I> = <code>kind(1.e0)</code>,
-  <code>kind(1.d0)</code>, according to the sparse matrix and preconditioner
-  data structure; note that the PSBLAS module <code>psb_base_mod</code>
-  provides the constants <code>psb_spk_</code>
-  = <code>kind(1.e0)</code> and <code>psb_dpk_</code> = <code>kind(1.d0)</code>;
-</LI>
-<LI>real parameters defining the preconditioner must be declared
-  according to the precision of the sparse matrix and preconditioner
-  data structures (see Section&nbsp;<A HREF="node17.html#sec:precset">6.2</A>).
-</LI>
-</UL>
-A description of each routine is given in the remainder of this section.
+<P>
+The setup and application of the default multi-level
+preconditioners for the real single precision and the complex, single and double
+precision, versions are obtained with straightforward modifications of the previous
+example (see Section&nbsp;<A HREF="node16.html#sec:userinterface">6</A> for details). If these versions are installed,
+the corresponding Fortran 95 codes are available in <code>examples/fileread/</code>.

 <P>

-<P>
-<BR><HR>
-<!--Table of Child-Links-->
-<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
+<DIV ALIGN="CENTER"><A NAME="fig:ex_default"></A><A NAME="926"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2:</STRONG>
+Setup and application of the default multi-level Schwarz preconditioner.
+</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+</DIV><TABLE  WIDTH="90%">
+<TR><TD> 
+<PRE>
+  use psb_base_mod
+  use mld_prec_mod
+  use psb_krylov_mod
+... ...
+!
+! sparse matrix
+  type(psb_dspmat_type) :: A
+! sparse matrix descriptor
+  type(psb_desc_type)   :: desc_A
+! preconditioner
+  type(mld_dprec_type)  :: P
+! right-hand side and solution vectors
+  real(kind(1.d0))      :: b(:), x(:)
+... ...
+!
+! initialize the parallel environment
+  call psb_init(ictxt)
+  call psb_info(ictxt,iam,np)
+... ...
+!
+! read and assemble the matrix A and the right-hand side b 
+! using PSBLAS routines for sparse matrix / vector management 
+... ...
+!
+! initialize the default multi-level preconditioner, i.e. hybrid
+! Schwarz, using RAS (with overlap 1 and ILU(0) on the blocks) 
+! as post-smoother and 4 block-Jacobi sweeps (with UMFPACK LU
+! on the blocks) as distributed coarse-level solver
+  call mld_precinit(P,'ML',info)
+!
+! build the preconditioner
+  call mld_precbld(A,desc_A,P,info)
+!
+! set the solver parameters and the initial guess
+  ... ...
+!
+! solve Ax=b with preconditioned BiCGSTAB
+  call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
+  ... ...
+!
+! deallocate the preconditioner
+  call mld_precfree(P,info)
+!
+! deallocate other data structures
+  ... ...
+!
+! exit the parallel environment
+  call psb_exit(ictxt)
+  stop
+</PRE>
+</TD></TR>
+</TABLE>
+<DIV ALIGN="CENTER">

-<UL>
-<LI><A NAME="tex2html241"
-  HREF="node16.html">Subroutine mld_precinit</A>
-<LI><A NAME="tex2html242"
-  HREF="node17.html">Subroutine mld_precset</A>
-<LI><A NAME="tex2html243"
-  HREF="node18.html">Subroutine mld_precbld</A>
-<LI><A NAME="tex2html244"
-  HREF="node19.html">Subroutine mld_precaply</A>
-<LI><A NAME="tex2html245"
-  HREF="node20.html">Subroutine mld_precfree</A>
-<LI><A NAME="tex2html246"
-  HREF="node21.html">Subroutine mld_precdescr</A>
-</UL>
-<!--End of Table of Child-Links-->
+</DIV></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+Different versions of multi-level preconditioners can be obtained by changing
+the default values of the preconditioner parameters. The code reported in
+Figure&nbsp;<A HREF="#fig:ex_3lh">3</A> shows how to set a three-level hybrid Schwarz
+preconditioner, which uses block Jacobi with ILU(0) on the
+local blocks as post-smoother, has a coarsest matrix replicated on the processors,
+and solves the coarsest-level system with the LU factorization from UMFPACK&nbsp;[<A
+ HREF="node25.html#UMFPACK">8</A>].
+The number of levels is specified by using <code>mld_precinit</code>; the other
+preconditioner parameters are set by calling <code>mld_precset</code>. Note that
+the type of multilevel framework (i.e. multiplicative among the levels
+with post-smoothing only) is not specified since it is the default 
+set by <code>mld_precinit</code>. 
+
+<P>
+Figure&nbsp;<A HREF="#fig:ex_3la">4</A> shows how to
+set a three-level additive Schwarz preconditioner,
+which uses RAS, with overlap 1 and ILU(0) on the blocks, 
+as pre- and post-smoother, and applies five block-Jacobi sweeps, with
+the UMFPACK LU factorization on the blocks, as distributed coarsest-level
+solver. Again, <code>mld_precset</code> is used only to set
+non-default values of the parameters (see Tables&nbsp;<A HREF="#tab:p_type">2</A>-<A HREF="#tab:p_coarse">5</A>).
+In both cases, the construction and the application of the preconditioner
+are carried out as for the default multi-level preconditioner.
+The code fragments shown in in Figures&nbsp;<A HREF="#fig:ex_3lh">3</A>-<A HREF="#fig:ex_3la">4</A> are
+included in the example program file <code>mld_dexample_ml.f90</code> too.
+
+<P>
+Finally, Figure&nbsp;<A HREF="#fig:ex_1l">5</A> shows the setup of a one-level
+additive Schwarz preconditioner, i.e. RAS with overlap 2. The corresponding
+example program is available in <code>mld_dexample_</code> <code>1lev.f90</code>.
+
+<P>
+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 <code>examples/pdegen</code>.
+
+<P>
+ 
+<BR><B>Remark 3.</B> Any PSBLAS-based program using the basic preconditioners
+implemented in PSBLAS 2.0, i.e. the diagonal and block-Jacobi ones,
+can use the diagonal and block-Jacobi preconditioners
+implemented in MLD2P4 without any change in the code.
+The PSBLAS-based program must be only recompiled
+and linked to the MLD2P4 library.
+
+<BR>
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:ex_3lh"></A><A NAME="928"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 3:</STRONG>
+Setup of a hybrid three-level Schwarz preconditioner.</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+</DIV><TABLE  WIDTH="90%">
+<TR><TD> 
+<PRE>
+... ...
+! set a three-level hybrid Schwarz preconditioner, which uses 
+! block Jacobi (with ILU(0) on the blocks) as post-smoother,
+! a coarsest matrix replicated on the processors, and the 
+! LU factorization from UMFPACK as coarse-level solver
+  call mld_precinit(P,'ML',info,nlev=3)
+  call_mld_precset(P,mld_smoother_type_,'BJAC',info)
+  call mld_precset(P,mld_coarse_mat_,'REPL',info)
+  call mld_precset(P,mld_coarse_solve_,'UMF',info)
+... ...
+</PRE>
+</TD></TR>
+</TABLE>
+<DIV ALIGN="CENTER">
+</DIV>
+<P>
+<DIV ALIGN="CENTER">
+</DIV></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:ex_3la"></A><A NAME="930"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 4:</STRONG>
+Setup of an additive three-level Schwarz preconditioner.</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+</DIV><TABLE  WIDTH="90%">
+<TR><TD> 
+<PRE>
+... ...
+! set a three-level additive Schwarz preconditioner, which uses 
+! RAS (with overlap 1 and ILU(0) on the blocks) as pre- and 
+! post-smoother, and 5 block-Jacobi sweeps (with UMFPACK LU
+! on the blocks) as distributed coarsest-level solver
+  call mld_precinit(P,'ML',info,nlev=3)
+  call mld_precset(P,mld_ml_type_,'ADD',info)
+  call_mld_precset(P,mld_smoother_pos_,'TWOSIDE',info)
+  call mld_precset(P,mld_coarse_sweeps_,5,info)
+... ...
+</PRE>
+</TD></TR>
+</TABLE>
+<DIV ALIGN="CENTER">
+</DIV>
+<P>
+<DIV ALIGN="CENTER">
+</DIV></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:ex_1l"></A><A NAME="932"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 5:</STRONG>
+Setup of a one-level Schwarz preconditioner.</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+</DIV><TABLE  WIDTH="90%">
+<TR><TD> 
+<PRE>
+... ...
+! set RAS with overlap 2 and ILU(0) on the local blocks
+  call mld_precinit(P,'AS',info)
+  call mld_precset(P,mld_sub_ovr_,2,info)
+... ...
+</PRE>
+</TD></TR>
+</TABLE>
+<DIV ALIGN="CENTER">
+
+</DIV></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
 <HR>
 <!--Navigation Panel-->
-<A NAME="tex2html239"
+<A NAME="tex2html242"
  HREF="node16.html">
 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="file:/usr/share/latex2html/icons/next.png"></A> 
-<A NAME="tex2html235"
-  HREF="userhtml.html">
+<A NAME="tex2html238"
+  HREF="node14.html">
 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="file:/usr/share/latex2html/icons/up.png"></A> 
-<A NAME="tex2html229"
+<A NAME="tex2html234"
  HREF="node14.html">
 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="file:/usr/share/latex2html/icons/prev.png"></A> 
-<A NAME="tex2html237"
+<A NAME="tex2html240"
  HREF="node2.html">
 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents"
 SRC="file:/usr/share/latex2html/icons/contents.png"></A>  
 <BR>
-<B> Next:</B> <A NAME="tex2html240"
-  HREF="node16.html">Subroutine mld_precinit</A>
-<B> Up:</B> <A NAME="tex2html236"
-  HREF="userhtml.html">userhtml</A>
-<B> Previous:</B> <A NAME="tex2html230"
-  HREF="node14.html">Examples</A>
- &nbsp; <B>  <A NAME="tex2html238"
+<B> Next:</B> <A NAME="tex2html243"
+  HREF="node16.html">User Interface</A>
+<B> Up:</B> <A NAME="tex2html239"
+  HREF="node14.html">Getting Started</A>
+<B> Previous:</B> <A NAME="tex2html235"
+  HREF="node14.html">Getting Started</A>
+ &nbsp; <B>  <A NAME="tex2html241"
  HREF="node2.html">Contents</A></B> 
 <!--End of Navigation Panel-->