From 320aff47cd17e2fafcf236eb0645ccd6162b7553 Mon Sep 17 00:00:00 2001 From: kolev1 Date: Thu, 27 Jan 2011 19:49:44 +0000 Subject: [PATCH] Updated the AMS documentation in the User and Reference Manuals. --- docs/usr_solvers.tex | 32 +++++++++++++++++++++++++------- krylov/HYPRE_krylov.h | 2 +- parcsr_ls/HYPRE_parcsr_ls.h | 15 +++++++++++++-- 3 files changed, 39 insertions(+), 10 deletions(-) diff --git a/docs/usr_solvers.tex b/docs/usr_solvers.tex index 467281203..7053676fa 100644 --- a/docs/usr_solvers.tex +++ b/docs/usr_solvers.tex @@ -477,7 +477,7 @@ there could be better choices than the two suggested ones. \section{AMS} \label{AMS} -AMS (Auxiliary space Maxwell Solver) is a parallel unstructured Maxwell +AMS (the Auxiliary-space Maxwell Solver) is a parallel unstructured Maxwell solver for edge finite element discretizations of the variational problem \begin{equation} \label{ams-maxwell} \mbox{Find } {\mathbf u} \in {\mathbf V}_h \>:\qquad @@ -552,6 +552,7 @@ with $G$, in which case the solver is a two-level method. AMS can be used either as a solver or as a preconditioner. Below we list the sequence of \hypre{} calls needed to create and use it as a solver. +See example code \file{ex15.c} for a complete implementation. We start with the allocation of the \code{HYPRE_Solver} object: \begin{display}\begin{verbatim} HYPRE_Solver solver; @@ -629,7 +630,7 @@ Here we use the following convention for the three subspace correction methods: $0$ refers to smoothing, $1$ stands for BoomerAMG based on $B_G$, and $2$ refers to a call to BoomerAMG for ${\mathbf B}_{{\mathbf \Pi}}$. -The values $3$, $4$ and $5$ refer to the scalar subspaspaces +The values $3$, $4$ and $5$ refer to the scalar subspaces corresponding to the $x$, $y$ and $z$ components of $\mathbf \Pi$. The abbreviation $xyyz$ for $x,y,z \in \{0,1,2,3,4,5\}$ @@ -642,7 +643,7 @@ In our experience the choices \code{cycle_type=1,5,8,11,13} often produced fastest solution times, while \code{cycle_type=7} resulted in smallest number of iterations. -Additional solver parameters, as the maximum number of iterations, +Additional solver parameters, such as the maximum number of iterations, the convergence tolerance and the output level, can be set with \begin{display}\begin{verbatim} HYPRE_AMSSetMaxIter(solver, maxit); /* default value: 20 */ @@ -665,9 +666,26 @@ To allow for this simplification, use the following \hypre{} call \begin{display}\begin{verbatim} HYPRE_AMSSetBetaPoissonMatrix(solver, NULL); \end{verbatim}\end{display} -If $\beta$ is zero only in parts of the domain, the problem is still -singular, but the AMS solver will try to detect this and construct -a non-singular preconditioner. + +If $\beta$ is zero only in parts of the domain, the problem is still singular, +but the AMS solver will try to detect this and construct a non-singular +preconditioner. Though this often works well in practice, AMS also provides a +more robust version for solving such singular problems to very low convergence +tolerances. This version takes advantage of additional information: the list of +nodes which are interior to a zero-conductivity region provided by the function +\begin{display}\begin{verbatim} +HYPRE_AMSSetInteriorNodes(solver, HYPRE_ParVector interior_nodes); +\end{verbatim}\end{display} +Based on the \code{interior_nodes} variable, a restricted discrete gradient +operator $G_0$ is constructed, and AMS is then defined based on the matrix +${\mathbf A}+\delta G_0^TG_0$ which is non-singular, and a small $\delta>0$ perturbation of +${\mathbf A}$. When iterating with this preconditioner, it is advantageous to project on +the compatible subspace $Ker(G_0^T)$. This can be done periodically, or manually +through the functions +\begin{display}\begin{verbatim} +HYPRE_AMSSetProjectionFrequency(solver, int projection_frequency); +HYPRE_AMSProjectOutGradients(solver, HYPRE_ParVector x); +\end{verbatim}\end{display} Two additional matrices are constructed in the setup of the AMS method---one corresponding to the coefficient $\alpha$ @@ -692,7 +710,7 @@ Note the following regarding these functions: the diagonal entries of the input matrix corresponding to eliminated degrees of freedom (due to essential boundary conditions) are penalized. -\item It is assumed that thei essential boundary conditions of +\item It is assumed that their essential boundary conditions of ${\mathbf A}$, \code{Abeta} and \code{Aalpha} are on the same part of the boundary. \item \code{HYPRE_AMSSetAlphaPoissonMatrix} forces the diff --git a/krylov/HYPRE_krylov.h b/krylov/HYPRE_krylov.h index 9d04203e9..04466b3cf 100644 --- a/krylov/HYPRE_krylov.h +++ b/krylov/HYPRE_krylov.h @@ -126,7 +126,7 @@ HYPRE_Int HYPRE_PCGSetAbsoluteTol(HYPRE_Solver solver, /** * (Optional) Set a residual-based convergence tolerance which checks if - * $\|r_old-r_new\| < rtol \|b\|$. This is useful when trying to converge to + * $\|r_{old}-r_{new}\| < rtol \|b\|$. This is useful when trying to converge to * very low relative and/or absolute tolerances, in order to bail-out before * roundoff errors affect the approximation. **/ diff --git a/parcsr_ls/HYPRE_parcsr_ls.h b/parcsr_ls/HYPRE_parcsr_ls.h index 575918fae..aa8342cd3 100644 --- a/parcsr_ls/HYPRE_parcsr_ls.h +++ b/parcsr_ls/HYPRE_parcsr_ls.h @@ -287,12 +287,12 @@ HYPRE_Int HYPRE_BoomerAMGSetGridRelaxType(HYPRE_Solver solver, * 4 & hybrid Gauss-Seidel or SOR, backward solve \\ * 5 & hybrid chaotic Gauss-Seidel (works only with OpenMP) \\ * 6 & hybrid symmetric Gauss-Seidel or SSOR \\ - * 8 & L1-scaled hybrid symmetric Gauss-Seidel\\ + * 8 & $\ell_1$-scaled hybrid symmetric Gauss-Seidel\\ * 9 & Gaussian elimination (only on coarsest level) \\ * 15 & CG (warning - not a fixed smoother - may require FGMRES)\\ * 16 & Chebyshev\\ * 17 & FCF-Jacobi\\ - * 18 & L1-scaled jacobi\\ + * 18 & $\ell_1$-scaled jacobi\\ * \hline * \end{tabular} **/ @@ -1476,6 +1476,17 @@ HYPRE_Int HYPRE_AMSSetPrintLevel(HYPRE_Solver solver, /** * (Optional) Sets relaxation parameters for $A$. * The defaults are $2$, $1$, $1.0$, $1.0$. + * + * The available options for relax\_type are: + * + * \begin{tabular}{|c|l|} \hline + * 1 & $\ell_1$-scaled Jacobi \\ + * 2 & $\ell_1$-scaled block symmetric Gauss-Seidel/SSOR \\ + * 3 & Kaczmarz \\ + * 4 & truncated version of $\ell_1$-scaled block symmetric Gauss-Seidel/SSOR \\ + * 16 & Chebyshev \\ + * \hline + * \end{tabular} **/ HYPRE_Int HYPRE_AMSSetSmoothingOptions(HYPRE_Solver solver, HYPRE_Int relax_type,