mld2p4-2:

Docs updates.
2026-10-06 22:55:12 +00:00 · 2017-04-21 13:29:28 +00:00
parent f47513eb80
commit 05ab5f4d55
79 changed files with 6788 additions and 8368 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>Subroutine smoothers_bld</TITLE>
-<META NAME="description" CONTENT="Subroutine smoothers_bld">
+<TITLE>Subroutine apply</TITLE>
+<META NAME="description" CONTENT="Subroutine apply">
 <META NAME="keywords" CONTENT="userhtml">
 <META NAME="resource-type" CONTENT="document">
 <META NAME="distribution" CONTENT="global">
@@ -20,54 +20,68 @@ original version by:  Nikos Drakos, CBLU, University of Leeds

 <LINK REL="next" HREF="node22.html">
 <LINK REL="previous" HREF="node20.html">
-<LINK REL="up" HREF="node16.html">
+<LINK REL="up" HREF="node15.html">
 <LINK REL="next" HREF="node22.html">
 </HEAD>

 <BODY >
 <!--Navigation Panel-->
-<A NAME="tex2html339"
+<A NAME="tex2html335"
  HREF="node22.html">
 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
-<A NAME="tex2html335"
-  HREF="node16.html">
+<A NAME="tex2html331"
+  HREF="node15.html">
 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
-<A NAME="tex2html329"
+<A NAME="tex2html325"
  HREF="node20.html">
 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
-<A NAME="tex2html337"
+<A NAME="tex2html333"
  HREF="node2.html">
 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>  
 <BR>
-<B> Next:</B> <A NAME="tex2html340"
-  HREF="node22.html">Subroutine apply</A>
-<B> Up:</B> <A NAME="tex2html336"
-  HREF="node16.html">User Interface</A>
-<B> Previous:</B> <A NAME="tex2html330"
-  HREF="node20.html">Subroutine hierarchy_bld</A>
- &nbsp; <B>  <A NAME="tex2html338"
+<B> Next:</B> <A NAME="tex2html336"
+  HREF="node22.html">Subroutine free</A>
+<B> Up:</B> <A NAME="tex2html332"
+  HREF="node15.html">User Interface</A>
+<B> Previous:</B> <A NAME="tex2html326"
+  HREF="node20.html">Subroutine smoothers_build</A>
+ &nbsp; <B>  <A NAME="tex2html334"
  HREF="node2.html">Contents</A></B> 
 <BR>
 <BR>
 <!--End of Navigation Panel-->

-<H2><A NAME="SECTION00085000000000000000"></A><A NAME="sec:smoothers_bld"></A>
+<H2><A NAME="SECTION00086000000000000000"></A><A NAME="sec:precapply"></A>
 <BR>
-Subroutine smoothers_bld
+Subroutine apply
 </H2>

 <P>
 <DIV ALIGN="CENTER">
-<code>call p%smoothers_bld(a,desc_a,p,info)</code>
+<code>call p%apply(x,y,desc_a,info [,trans,work])</code>
 <BR>
 </DIV>

 <P>
-This routine builds the smoothers and the coarsest-level solvers for the
-multi-level preconditioner <code>p</code>, according to the requirements made by
-the user through the routines <code>init</code> and <code>set</code>, and based on the aggregation
-hierarchy produced by a previous call to <code>hierarchy_bld</code>
-(see Section&nbsp;<A HREF="node20.html#sec:hier_bld">6.4</A>). 
+This routine computes <!-- MATH
+ $y = op(M^{-1})\, x$
+ -->
+<IMG
+ WIDTH="117" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
+ SRC="img34.png"
+ ALT="$y = op(M^{-1})  x$">, where <IMG
+ WIDTH="23" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
+ SRC="img35.png"
+ ALT="$M$"> is a previously built
+preconditioner, stored into <code>p</code>, and <IMG
+ WIDTH="22" HEIGHT="31" ALIGN="MIDDLE" BORDER="0"
+ SRC="img36.png"
+ ALT="$op$">
+denotes the preconditioner itself or its transpose, according to
+the value of <code>trans</code>.
+Note that, when MLD2P4 is used with a Krylov solver from PSBLAS,
+<code>p%apply</code> is called within the PSBLAS routine <code>psb_krylov</code>
+and hence it is completely transparent to the user.

 <P>
 <FONT SIZE="+1"><B>Arguments</B></FONT> 
@@ -75,35 +89,122 @@ hierarchy produced by a previous call to <code>hierarchy_bld</code>

 <P>
 <TABLE CELLPADDING=3>
-<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>a</code></TD>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><code>type(psb_</code><I>x</I><code>spmat_type), intent(in)</code>.</TD>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>x</code></TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><I>type</I><code>(</code><I>kind_parameter</I><code>), dimension(:), intent(in)</code>.</TD>
 </TR>
 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>The sparse matrix structure containing the local part of the
-                matrix to be preconditioned. Note that <I>x</I> must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.
-                See the PSBLAS User's Guide for details [<A
- HREF="node28.html#PSBLASGUIDE">16</A>].</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>The local part of the vector <IMG
+ WIDTH="14" HEIGHT="18" ALIGN="BOTTOM" BORDER="0"
+ SRC="img37.png"
+ ALT="$x$">. Note that <I>type</I> and   
+                <I>kind_parameter</I> must be chosen according
+                to the real/complex, single/double precision version of MLD2P4 under use.</TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>y</code></TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><I>type</I><code>(</code><I>kind_parameter</I><code>), dimension(:), intent(out)</code>.</TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>The local part of the vector <IMG
+ WIDTH="14" HEIGHT="31" ALIGN="MIDDLE" BORDER="0"
+ SRC="img38.png"
+ ALT="$y$">. Note that <I>type</I> and
+                <I>kind_parameter</I> must be chosen according
+                to the real/complex, single/double precision version of MLD2P4 under use.</TD>
 </TR>
 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>desc_a</code></TD>
 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><code>type(psb_desc_type), intent(in)</code>.</TD>
 </TR>
 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>The communication descriptor of <code>a</code>. See the PSBLAS User's Guide for
-                details [<A
- HREF="node28.html#PSBLASGUIDE">16</A>].</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>The communication descriptor associated to the matrix to be
+                preconditioned.</TD>
 </TR>
 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>info</code></TD>
 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><code>integer, intent(out)</code>.</TD>
 </TR>
 <TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>Error code. If no error, 0 is returned. See Section&nbsp;<A HREF="node26.html#sec:errors">8</A> for details.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>Error code. If no error, 0 is returned. See Section&nbsp;<A HREF="node25.html#sec:errors">8</A> for details.</TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>trans</code></TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><code>character(len=1), optional, intent(in).</code></TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>If <code>trans</code> = <code>'N','n'</code> then <!-- MATH
+ $op(M^{-1}) = M^{-1}$
+ -->
+<IMG
+ WIDTH="132" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
+ SRC="img39.png"
+ ALT="$op(M^{-1}) = M^{-1}$">;
+                if <code>trans</code> = <code>'T','t'</code> then <!-- MATH
+ $op(M^{-1}) = M^{-T}$
+ -->
+<IMG
+ WIDTH="135" HEIGHT="40" ALIGN="MIDDLE" BORDER="0"
+ SRC="img40.png"
+ ALT="$op(M^{-1}) = M^{-T}$">
+                (transpose of <IMG
+ WIDTH="48" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
+ SRC="img41.png"
+ ALT="$M^{-1})$">;  if <code>trans</code> = <code>'C','c'</code> then <!-- MATH
+ $op(M^{-1}) = M^{-C}$
+ -->
+<IMG
+ WIDTH="136" HEIGHT="40" ALIGN="MIDDLE" BORDER="0"
+ SRC="img42.png"
+ ALT="$op(M^{-1}) = M^{-C}$">
+                (conjugate transpose of <IMG
+ WIDTH="48" HEIGHT="39" ALIGN="MIDDLE" BORDER="0"
+ SRC="img41.png"
+ ALT="$M^{-1})$">.</TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34><code>work</code></TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340><I>type</I><code>(</code><I>kind_parameter</I><code>), dimension(:), optional, target</code>.</TD>
+</TR>
+<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=34>&nbsp;</TD>
+<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=340>Workspace. Its size should be at
+               least <code>4 * psb_cd_get_local_</code> <code>cols(desc_a)</code> (see the PSBLAS User's Guide).
+               Note that <I>type</I> and <I>kind_parameter</I> must be chosen according
+               to the real/complex, single/double precision version of MLD2P4 under use.</TD>
 </TR>
 </TABLE>

 <P>
+For compatibility with the previous versions of MLD2P4, this routine can be also invoked
+as follows:

-<BR><HR>
+<P>
+<DIV ALIGN="CENTER">
+<code>call mld_precaply(p,what,val,info)</code>
+
+</DIV>
+
+<P>
+
+<P>
+<HR>
+<!--Navigation Panel-->
+<A NAME="tex2html335"
+  HREF="node22.html">
+<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
+<A NAME="tex2html331"
+  HREF="node15.html">
+<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
+<A NAME="tex2html325"
+  HREF="node20.html">
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
+<A NAME="tex2html333"
+  HREF="node2.html">
+<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>  
+<BR>
+<B> Next:</B> <A NAME="tex2html336"
+  HREF="node22.html">Subroutine free</A>
+<B> Up:</B> <A NAME="tex2html332"
+  HREF="node15.html">User Interface</A>
+<B> Previous:</B> <A NAME="tex2html326"
+  HREF="node20.html">Subroutine smoothers_build</A>
+ &nbsp; <B>  <A NAME="tex2html334"
+  HREF="node2.html">Contents</A></B> 
+<!--End of Navigation Panel-->

 </BODY>
 </HTML>