/[escript]/trunk/doc/user/linearPDE.tex
ViewVC logotype

Annotation of /trunk/doc/user/linearPDE.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6928 - (hide annotations)
Mon Dec 9 05:29:21 2019 UTC (3 months, 3 weeks ago) by acodd
File MIME type: application/x-tex
File size: 47979 byte(s)
more updates to userguide 

1 ksteube 1811
2 jfenwick 3989 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 jfenwick 6651 % Copyright (c) 2003-2018 by The University of Queensland
4 jfenwick 3989 % http://www.uq.edu.au
5 gross 625 %
6 ksteube 1811 % Primary Business: Queensland, Australia
7 jfenwick 6112 % Licensed under the Apache License, version 2.0
8     % http://www.apache.org/licenses/LICENSE-2.0
9 gross 625 %
10 jfenwick 3989 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 jfenwick 4657 % Development 2012-2013 by School of Earth Sciences
12     % Development from 2014 by Centre for Geoscience Computing (GeoComp)
13 jfenwick 3989 %
14     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 jgs 102
16 caltinay 3293 \chapter{The \linearPDEs Module}
17 jgs 102
18 gross 999 \section{Linear Partial Differential Equations}
19 jgs 102 \label{SEC LinearPDE}
20    
21 caltinay 3316 The \LinearPDE class is used to define a general linear, steady, second order
22     PDE for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.
23     In the following $\Gamma$ denotes the boundary of the domain $\Omega$ and $n$
24     denotes the outer normal field on $\Gamma$.
25 jgs 102
26 caltinay 3316 For a single PDE with a solution that has a single component the linear PDE is
27 aellery 6687 defined in the following form \footnote{This PDE system can be written in the equivalent form, \begin{align*} \centering \, -\nabla \cdot \left( \textbf{A} \nabla u \right) - \nabla \cdot \left( \textbf{B} \, u \right) + \textbf{C} \cdot \nabla u + \textbf{D} \, u + \sum_p \delta(p) u(p) &= - \nabla \cdot \textbf{X} + \textbf{Y} + \sum_p \delta(p), \\
28     \hat{\textbf{n}} \cdot \left( \textbf{A} \nabla u + \textbf{B} \, u \right) + \textbf{d} \, u &= \hat{\textbf{n}} \cdot \textbf{X} + \textbf{y},
29 acodd 6927 \end{align*} where bold font denotes a data object and $\hat{\textbf{n}}$ denotes a unit vector normal. The weak form for this is
30     \begin{equation*}\int_{\Omega} (\nabla v)\cdot \left( \textbf{A} \nabla u \right) +( \nabla v) \cdot \left( \textbf{B} \, u \right) + v\textbf{C} \cdot \nabla u + \textbf{D} \,v u + \sum_p \delta(p) u(p)v \;d\Omega = \int_{\Omega}(\nabla v) \cdot \textbf{X} + \textbf{Y}v + \sum_p \delta(p)v\; d\Omega.
31     \end{equation*}
32     }
33 jgs 102 \begin{equation}\label{LINEARPDE.SINGLE.1}
34 gross 5670 -(A_{jl} u_{,l})_{,j}-(B_{j} u)_{,j}+C_{l} u_{,l}+D u + \sum_p d^{dirac}(p) \; u(p) =-X_{j,j}+Y + \sum_p y^{dirac}(p) \; .
35 jgs 102 \end{equation}
36 caltinay 3316 $u_{,j}$ denotes the derivative of $u$ with respect to the $j$-th spatial direction.
37     Einstein's summation convention, i.e. summation over indexes appearing twice
38 gross 5670 in a term of a sum, is used in this chapter. $y^{dirac}(p)$ represent a nodal source term
39     at point $p$, cf. $y^{dirac}(p) $ and similar $d^{dirac}(p)$ define Dirac delta-function
40     terms.
41 caltinay 3316 The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through
42     \Data objects in the \Function on the PDE or objects that can be converted
43 gross 5670 into such \Data objects. $d^{dirac}$
44 caltinay 3316 $A$ is a \RankTwo, $B$, $C$ and $X$ are each a \RankOne and $D$ and $Y$ are
45 gross 5670 scalars. $y^{dirac}$ and $d^{dirac}$ are each scalars in the \DiracDeltaFunctions.
46 aellery 6687 The following natural boundary conditions are considered\index{boundary condition!natural} on $\Gamma$:
47 jgs 102 \begin{equation}\label{LINEARPDE.SINGLE.2}
48 jfenwick 3295 n_{j}(A_{jl} u_{,l}+B_{j} u)+d u=n_{j}X_{j} + y \;.
49 jgs 102 \end{equation}
50 caltinay 3316 Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE.
51     The coefficients $d$ and $y$ are each a \Scalar in the \FunctionOnBoundary.
52     Constraints\index{constraint} for the solution prescribe the value of the
53 jgs 102 solution at certain locations in the domain. They have the form
54     \begin{equation}\label{LINEARPDE.SINGLE.3}
55     u=r \mbox{ where } q>0
56     \end{equation}
57 caltinay 3316 $r$ and $q$ are each a \Scalar where $q$ is the characteristic function\index{characteristic function}
58     defining where the constraint is applied.
59     The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other
60     condition set by \eqn{LINEARPDE.SINGLE.1} or \eqn{LINEARPDE.SINGLE.2}.
61 gross 625
62 jgs 102 For a system of PDEs and a solution with several components the PDE has the form
63     \begin{equation}\label{LINEARPDE.SYSTEM.1}
64 gross 5670 -(A_{ijkl} u_{k,l})_{,j}-(B_{ijk} u_{k})_{,j}+C_{ikl} u_{k,l}+D_{ik} u_{k}+
65     \sum_p d^{dirac}_{ik}(p) \; u_i(p)
66     =-X_{ij,j}+Y_{i} +\sum_p \; y^{dirac}_i(p) \; .
67 jgs 102 \end{equation}
68 gross 5670 $A$ is a \RankFour, $B$ and $C$ are each a \RankThree, $D$, $d^{dirac}$ and $X$ are each a \RankTwo and $Y$ and $y^{dirac}$ is a \RankOne.
69 caltinay 3316 The natural boundary conditions\index{boundary condition!natural} take the form:
70 jgs 102 \begin{equation}\label{LINEARPDE.SYSTEM.2}
71 jfenwick 3295 n_{j}(A_{ijkl} u_{k,l}+B_{ijk} u_{k})+d_{ik} u_{k}=n_{j}X_{ij}+y_{i} \;.
72 jgs 102 \end{equation}
73 caltinay 3316 The coefficient $d$ is a \RankTwo and $y$ is a \RankOne both in the
74     \FunctionOnBoundary. Constraints\index{constraint} take the form
75 jgs 102 \begin{equation}\label{LINEARPDE.SYSTEM.3}
76 jfenwick 3295 u_{i}=r_{i} \mbox{ where } q_{i}>0
77 jgs 102 \end{equation}
78 caltinay 3316 $r$ and $q$ are each a \RankOne. Notice that not necessarily all components
79 acodd 6927 must have a constraint at all locations. An example for a system of PDEs is shown in the elastic deformation example in section \ref{ELASTIC CHAP}
80 gross 625
81 caltinay 3316 \LinearPDE also supports solution discontinuities\index{discontinuity} over a
82     contact region $\Gamma^{contact}$ in the domain $\Omega$.
83     To specify the conditions across the discontinuity we are using the
84     generalised flux $J$\footnote{In some applications the definition of flux used
85     here can be different from the commonly used definition.
86     For instance, if $T$ is a temperature field the heat flux $q$ is defined as
87     $q_{,i}=-\kappa T_{,i}$ ($\kappa$ is the diffusivity) which differs from the
88     definition used here by the sign. This needs to be kept in mind when defining
89     natural boundary conditions\index{boundary condition!natural}.} which in
90     the case of a system of PDEs and several components of the solution, is
91 gross 660 defined as
92 jgs 102 \begin{equation}\label{LINEARPDE.SYSTEM.5}
93 jfenwick 3295 J_{ij}=A_{ijkl}u_{k,l}+B_{ijk}u_{k}-X_{ij}
94 jgs 102 \end{equation}
95 caltinay 3316 For the case of single solution component and single PDE, $J$ is defined as
96 jgs 102 \begin{equation}\label{LINEARPDE.SINGLE.5}
97 jfenwick 3295 J_{j}=A_{jl}u_{,l}+B_{j}u_{k}-X_{j}
98 jgs 102 \end{equation}
99 caltinay 3316 In the context of discontinuities\index{discontinuity} $n$ denotes the normal
100     on the discontinuity pointing from side 0 towards side 1.
101     For a system of PDEs the contact condition takes the form
102 jgs 102 \begin{equation}\label{LINEARPDE.SYSTEM.6}
103 jfenwick 3295 n_{j} J^{0}_{ij}=n_{j} J^{1}_{ij}=y^{contact}_{i} - d^{contact}_{ik} [u]_{k} \; .
104 jgs 102 \end{equation}
105     where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the
106     discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference
107     of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.
108 gross 660 The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a
109 jgs 102 \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.
110 caltinay 3316 In the case of a single PDE and a single component solution the contact
111     condition takes the form
112 jgs 102 \begin{equation}\label{LINEARPDE.SINGLE.6}
113 jfenwick 3295 n_{j} J^{0}_{j}=n_{j} J^{1}_{j}=y^{contact} - d^{contact}[u]
114 jgs 102 \end{equation}
115 jfenwick 6678 In this case the coefficient $d^{contact}$ and $y^{contact}$ are each
116     \Scalars both in either\\
117     the \FunctionOnContactZero or the \FunctionOnContactOne.
118 gross 625
119 caltinay 3316 The PDE is symmetrical\index{symmetrical} if
120 gross 625 \begin{equation}\label{LINEARPDE.SINGLE.4}
121 jfenwick 3295 A_{jl}=A_{lj} \mbox{ and } B_{j}=C_{j}
122 gross 625 \end{equation}
123 caltinay 3316 The system of PDEs is symmetrical\index{symmetrical} if
124 gross 625 \begin{eqnarray}
125     \label{LINEARPDE.SYSTEM.4}
126 jfenwick 3295 A_{ijkl}&=&A_{klij} \\
127     B_{ijk}&=&C_{kij} \\
128     D_{ik}&=&D_{ki} \\
129     d_{ik}&=&d_{ki} \\
130     d^{contact}_{ik}&=&d^{contact}_{ki}
131 gross 625 \end{eqnarray}
132 caltinay 3316 Note that in contrast to the scalar case \eqn{LINEARPDE.SINGLE.4} now the
133     coefficients $D$, $d$ and $d^{contact}$ have to be inspected.
134 gross 625
135 caltinay 3316 The following example illustrates a typical usage of the \LinearPDE class:
136 gross 2474 \begin{python}
137 caltinay 3316 from esys.escript import *
138     from esys.escript.linearPDEs import LinearPDE
139     from esys.finley import Rectangle
140     mydomain = Rectangle(l0=1., l1=1., n0=40, n1=20)
141     mypde=LinearPDE(mydomain)
142     mypde.setSymmetryOn()
143     mypde.setValue(A=kappa*kronecker(mydomain), D=1, Y=1)
144     u=mypde.getSolution()
145 gross 2474 \end{python}
146 caltinay 3316 We refer to \Chap{CHAP: Tutorial} for more details.
147 gross 999
148 caltinay 3316 An instance of the \SolverOptions class is attached to the \LinearPDE class
149     object. It holds options for the solver that may be set before solving the PDE.
150     In the following example the \method{getSolverOptions} method is used to
151     access the \SolverOptions object attached to \var{mypde}:
152 gross 2474 \begin{python}
153 caltinay 3316 from esys.escript import *
154     from esys.escript.linearPDEs import LinearPDE, SolverOptions
155     from esys.finley import Rectangle
156     mydomain = Rectangle(l0=1., l1=1., n0=40, n1=20)
157     mypde=LinearPDE(mydomain)
158     mypde.setValue(A=kappa*kronecker(mydomain), D=1, Y=1)
159     mypde.getSolverOptions().setVerbosityOn()
160     mypde.getSolverOptions().setSolverMethod(SolverOptions.PCG)
161     mypde.getSolverOptions().setPreconditioner(SolverOptions.AMG)
162     mypde.getSolverOptions().setTolerance(1e-8)
163     mypde.getSolverOptions().setIterMax(1000)
164     u=mypde.getSolution()
165 gross 2474 \end{python}
166 jfenwick 3301 In this example, the preconditioned conjugate gradient method \PCG is used
167 gross 2864 with preconditioner \AMG. The relative tolerance is set to $10^{-8}$ and
168 gross 2474 the maximum number of iteration steps to $1000$.
169 caltinay 3316 After a completed call to \method{getSolution()}, the attached \SolverOptions
170     object gives access to diagnostic information:
171 gross 2474 \begin{python}
172 caltinay 3316 u=mypde.getSolution()
173     print("Number of iteration steps =", mypde.getDiagnostics("num_iter"))
174     print("Total solution time =", mypde.getDiagnostics("time"))
175     print("Set-up time =", mypde.getDiagnostics("set_up_time"))
176     print("Net time =", mypde.getDiagnostics("net_time"))
177 jfenwick 6678 print("Residual norm of returned solution =",
178     mypde.getDiagnostics('residual_norm'))
179 gross 2474 \end{python}
180 caltinay 3316 Typically, a negative value for a diagnostic variable indicates that it is
181 acodd 6927 undefined. For more details on \SolverOptions and Trilinos see chapter \ref{TRILINOS}.
182 gross 2474
183 gross 999 \subsection{Classes}
184 caltinay 3306 %\declaremodule{extension}{esys.escript.linearPDEs}
185     %\modulesynopsis{Linear partial differential equation handler}
186 gross 999 The module \linearPDEs provides an interface to define and solve linear partial
187 caltinay 3316 differential equations within \escript. The module \linearPDEs does not
188     provide any solver capabilities in itself but hands the PDE over to the PDE
189     solver library defined through the \Domain of the PDE, e.g. \finley.
190 gross 2474 The general interface is provided through the \LinearPDE class. The \Poisson
191 caltinay 5298 class which is also derived form the \LinearPDE class can be used to define
192 caltinay 3316 the Poisson equation\index{Poisson}.
193 gross 999
194     \subsection{\LinearPDE class}
195 caltinay 3316 This is the general class to define a linear PDE in \escript.
196     We list a selection of the most important methods of the class.
197     For a complete list, see the reference at \ReferenceGuide.
198 gross 625
199 jgs 102 \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
200 caltinay 3316 opens a linear, steady, second order PDE on the \Domain \var{domain}.
201     The parameters \var{numEquations} and \var{numSolutions} give the number of
202     equations and the number of solution components.
203     If \var{numEquations} and \var{numSolutions} are non-positive, then the number
204     of equations and the number of solutions, respectively, stay undefined until a
205     coefficient is defined.
206 jgs 102 \end{classdesc}
207    
208 jfenwick 1959 \subsubsection{\LinearPDE methods}
209 gross 625 \begin{methoddesc}[LinearPDE]{setValue}{
210 gross 660 \optional{A}\optional{, B},
211     \optional{, C}\optional{, D}
212     \optional{, X}\optional{, Y}
213     \optional{, d}\optional{, y}
214     \optional{, d_contact}\optional{, y_contact}
215 gross 5670 \optional{, d_dirac}\optional{, y_dirac}
216     \optional{, q}\optional{, r}, }
217 caltinay 3316 assigns new values to coefficients. By default all values are assumed to be
218     zero\footnote{In fact, it is assumed they are not present by assigning the
219     value \code{escript.Data()}. This can be used by the solver library to reduce
220     computational costs.}.
221     If the new coefficient value is not a \Data object, it is converted into a
222     \Data object in the appropriate \FunctionSpace.
223 jgs 102 \end{methoddesc}
224    
225     \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
226 caltinay 3316 returns the value assigned to coefficient \var{name}. If \var{name} is not a
227     valid name an exception is raised.
228 jgs 102 \end{methoddesc}
229    
230     \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
231 caltinay 3316 returns the shape of the coefficient \var{name} even if no value has been
232     assigned to it.
233 jgs 102 \end{methoddesc}
234    
235 gross 625 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
236 caltinay 3316 returns the \FunctionSpace of the coefficient \var{name} even if no value has
237     been assigned to it.
238 jgs 102 \end{methoddesc}
239    
240     \begin{methoddesc}[LinearPDE]{setDebugOn}{}
241 caltinay 3316 switches on debug mode so more diagnostic messages will be printed.
242 jgs 102 \end{methoddesc}
243    
244     \begin{methoddesc}[LinearPDE]{setDebugOff}{}
245 jfenwick 1959 switches off debug mode.
246 jgs 102 \end{methoddesc}
247    
248 gross 2474 \begin{methoddesc}[LinearPDE]{getSolverOptions}{}
249 caltinay 3316 returns the solver options for solving the PDE. In fact, the method returns
250     a \SolverOptions class object which can be used to modify the tolerance,
251     the solver or the preconditioner, see \Sec{SEC Solver Options} for details.
252 jgs 102 \end{methoddesc}
253    
254 gross 2474 \begin{methoddesc}[LinearPDE]{setSolverOptions}{\optional{options=None}}
255 caltinay 3316 sets the solver options for solving the PDE. If argument \var{options} is
256     present it must be a \SolverOptions class object, see \Sec{SEC Solver Options}
257     for details. Otherwise the solver options are reset to the default.
258 jgs 102 \end{methoddesc}
259    
260 gross 2474 \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
261 gross 3379 returns \True if matrix lumping is set as the solver for the system of linear
262 caltinay 3316 equations, \False otherwise.
263 gross 653 \end{methoddesc}
264    
265 gross 625 \begin{methoddesc}[LinearPDE]{getDomain}{}
266     returns the \Domain of the PDE.
267 jgs 102 \end{methoddesc}
268    
269 gross 625 \begin{methoddesc}[LinearPDE]{getDim}{}
270 caltinay 5298 returns the number of spatial dimensions of the PDE.
271 jgs 102 \end{methoddesc}
272    
273 gross 625 \begin{methoddesc}[LinearPDE]{getNumEquations}{}
274     returns the number of equations.
275     \end{methoddesc}
276 jgs 102
277 gross 625 \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
278     returns the number of components of the solution.
279 jgs 102 \end{methoddesc}
280    
281 gross 625 \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
282 caltinay 3316 returns \True if the PDE is symmetric, \False otherwise.
283     The method is very computationally expensive and should only be called for
284     testing purposes. The symmetry flag is not altered.
285     If \var{verbose=True} information about where symmetry is violated is printed.
286 jgs 102 \end{methoddesc}
287    
288 gross 625 \begin{methoddesc}[LinearPDE]{getFlux}{u}
289 caltinay 3316 returns the flux $J_{ij}$\index{flux} for given solution \var{u} defined by
290     \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}.
291 jgs 102 \end{methoddesc}
292    
293     \begin{methoddesc}[LinearPDE]{isSymmetric}{}
294 caltinay 3316 returns \True if the PDE has been indicated to be symmetric, \False otherwise.
295 jgs 102 \end{methoddesc}
296    
297     \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
298 caltinay 5298 indicates that the PDE is symmetric which enables the use of certain solvers
299     and can potentially speed up the solver.
300 jgs 102 \end{methoddesc}
301    
302     \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
303     indicates that the PDE is not symmetric.
304     \end{methoddesc}
305    
306     \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
307 caltinay 3316 enables the reduction of polynomial order for the solution and equation
308     evaluation even if a quadratic or higher interpolation order is defined in the
309     \Domain. This feature may not be supported by all PDE libraries.
310 jgs 102 \end{methoddesc}
311    
312     \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
313 caltinay 3316 disables the reduction of polynomial order for the solution and equation evaluation.
314 jgs 102 \end{methoddesc}
315    
316     \begin{methoddesc}[LinearPDE]{getOperator}{}
317     returns the \Operator of the PDE.
318     \end{methoddesc}
319    
320 gross 625 \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
321 caltinay 3316 returns the right hand side of the PDE as a \Data object.
322 jgs 102 \end{methoddesc}
323    
324     \begin{methoddesc}[LinearPDE]{getSystem}{}
325 caltinay 5298 returns the \Operator and right hand side of the PDE as a tuple.
326 jgs 102 \end{methoddesc}
327    
328 gross 2474 \begin{methoddesc}[LinearPDE]{getSolution}{}
329 caltinay 3316 returns (an approximation of) the solution of the PDE. This call will invoke
330     the discretization of the PDE and the solution of the resulting system of
331     linear equations. Keep in mind that this call is typically computationally
332     expensive and -- depending on the PDE and the discretization -- can take a
333     long time to complete.
334 jgs 102 \end{methoddesc}
335    
336 gross 2474 \subsection{The \Poisson Class}
337     The \Poisson class provides an easy way to define and solve the Poisson
338     equation
339     \begin{equation}\label{POISSON.1}
340 caltinay 3316 -u_{,ii}=f
341 gross 2474 \end{equation}
342     with homogeneous boundary conditions
343     \begin{equation}\label{POISSON.2}
344 jfenwick 3295 n_{i}u_{,i}=0
345 gross 2474 \end{equation}
346     and homogeneous constraints
347     \begin{equation}\label{POISSON.3}
348 caltinay 3316 u=0 \mbox{ where } q>0 .
349 gross 2474 \end{equation}
350 caltinay 3316 $f$ has to be a \Scalar in the \Function and $q$ must be a \Scalar in the \SolutionFS.
351 gross 2474
352     \begin{classdesc}{Poisson}{domain}
353     opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
354     \end{classdesc}
355     \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
356     assigns new values to \var{f} and \var{q}.
357     \end{methoddesc}
358    
359     \subsection{The \Helmholtz Class}
360     The \Helmholtz class defines the Helmholtz problem
361     \begin{equation}\label{HZ.1}
362 jfenwick 3295 \omega \; u - (k\; u_{,j})_{,j} = f
363 gross 2474 \end{equation}
364 caltinay 3316 with natural boundary conditions
365 gross 2474 \begin{equation}\label{HZ.2}
366 caltinay 3316 k\; u_{,j} n_{,j} = g- \alpha \; u
367 gross 2474 \end{equation}
368 caltinay 3316 and constraints
369 gross 2474 \begin{equation}\label{HZ.3}
370 caltinay 3316 u=r \mbox{ where } q>0 .
371 gross 2474 \end{equation}
372 caltinay 3316 $\omega$, $k$, and $f$ each have to be a \Scalar in the \Function, $g$ and
373     $\alpha$ must be a \Scalar in the \FunctionOnBoundary, and $q$ and $r$ must be
374     a \Scalar in the \SolutionFS or must be mapped or interpolated into the
375     particular \FunctionSpace.
376 gross 2474
377     \begin{classdesc}{Helmholtz}{domain}
378     opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE.
379     \end{classdesc}
380     \begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}}
381 caltinay 3316 assigns new values to \var{omega}, \var{k}, \var{f}, \var{alpha}, \var{g},
382     \var{r}, and \var{q}. By default all values are set to zero.
383 gross 2474 \end{methoddesc}
384    
385     \subsection{The \Lame Class}
386 sshaw 5284 The \Lame class defines a Lam\'e equation problem
387 gross 2474 \begin{equation}\label{LE.1}
388 jfenwick 3295 -(\mu (u_{i,j}+u_{j,i})+\lambda u_{k,k}\delta_{ij})_{j} = F_{i}-\sigma_{ij,j}
389 gross 2474 \end{equation}
390 caltinay 3316 with natural boundary conditions
391 gross 2474 \begin{equation}\label{LE.2}
392 jfenwick 3295 n_{j}(\mu \; (u_{i,j}+u_{j,i})+\lambda u_{k,k}\delta_{ij}) = f_{i}+n_{j}\sigma_{ij}
393 gross 2474 \end{equation}
394     and constraint
395     \begin{equation}\label{LE.3}
396 caltinay 3316 u_{i}=r_{i} \mbox{ where } q_{i}>0 .
397 gross 2474 \end{equation}
398 caltinay 3316 $\mu$, $\lambda$ have to be a \Scalar in the \Function, $F$ has to be a
399     \Vector in the \Function, $\sigma$ has to be a \Tensor in the \Function,
400     $f$ must be a \Vector in the \FunctionOnBoundary, and $q$ and $r$ must be a
401     \Vector in the \SolutionFS or must be mapped or interpolated into the
402     particular \FunctionSpace.
403 gross 2474
404     \begin{classdesc}{Lame}{domain}
405 sshaw 5284 opens a Lam\'e equation on the \Domain domain. \Lame is derived from \LinearPDE.
406 gross 2474 \end{classdesc}
407     \begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}}
408 caltinay 3316 assigns new values to \var{lame_lambda}, \var{lame_mu}, \var{F}, \var{sigma},
409     \var{f}, \var{r}, and \var{q}. By default all values are set to zero.
410 gross 2474 \end{methoddesc}
411    
412 gross 2864 \section{Projection}
413 caltinay 3306 %\declaremodule{extension}{esys.escript.pdetools}
414 gross 2864 \label{SEC Projection}
415    
416 caltinay 3316 Using the \LinearPDE class provides an option to change the \FunctionSpace
417     attribute in addition to the standard interpolation mechanism\index{interpolation}
418     as discussed in \Chap{ESCRIPT CHAP}. If you consider the stripped-down version
419 gross 2864 \begin{equation}\label{PROJ.1}
420     u = Y
421     \end{equation}
422 caltinay 3316 of the general scalar PDE~\ref{LINEARPDE.SINGLE.1} (boundary conditions are
423     irrelevant), you can see the solution $u$ of this PDE as a projection of the
424     input function $Y$ which has the \Function attribute to a function with the
425     \SolutionFS or \ReducedSolutionFS attribute.
426     In fact, the solution maps values defined at element centers representing a
427     possibly discontinuous function onto a continuous function represented by its
428     values at the nodes of the FEM mesh.
429     This mapping is called a projection\index{projection}. Projection can be a
430     useful tool but needs to be applied with some care due to the possibility of
431     projecting a potentially discontinuous function onto a continuous function,
432     although this may also be a desirable effect, for instance to smooth a function.
433     The projection of the gradient of a function typically calculated on the
434     element center to the nodes of a FEM mesh can be evaluated on the domain
435     boundary and so projection provides a tool to extrapolate the gradient from
436     the internal to the boundary. This is only a reasonable procedure in the
437     absence of singularities at the boundary.
438 gross 2864
439 caltinay 3316 As projection is often used in simulations \escript provides an easy to use
440     class \class{Projector} which is part of the \pdetools module.
441     The following script demonstrates the usage of the class to project the
442     piecewise constant function ($=1$ for $x_{0}\ge 0.5$ and $=-1$ for $x_{0}<0.5$)
443     to a function with the \ReducedSolutionFS attribute (default target):
444 gross 2864 \begin{python}
445 caltinay 3316 from esys.escript.pdetools import Projector
446     proj=Projector(domain)
447     x0=domain.getX()[0]
448     jmp=1.-2.*wherePositive(x0-0.5)
449     u=proj.getValue(jmp)
450     # alternative call:
451     u=proj(jmp)
452 gross 2864 \end{python}
453 caltinay 3316 By default the class uses lumping to solve the PDE~\ref{PROJ.1}.
454     This technique is faster than using the standard solver techniques of PDEs.
455     In essence it leads to using the average of neighbour element values to
456     calculate the value at each FEM node.
457 gross 2864
458 caltinay 3316 The following script illustrates how to evaluate the normal stress on the
459     boundary from a given displacement field \var{u}:
460 gross 2864 \begin{python}
461 caltinay 3316 from esys.escript.pdetools import Projector
462     u=...
463     proj=Projector(u.getDomain())
464     e=symmetric(grad(u))
465     stress = G*e+ (K-2./3.*G)*trace(e)*kronecker(u.getDomain())
466     normal_stress = inner(u.getDomain().getNormal(), proj(stress))
467 gross 2864 \end{python}
468    
469     \begin{classdesc}{Projector}{domain\optional{, reduce=\True \optional{, fast=\True}}}
470 caltinay 3316 This class defines a projector on the domain \var{domain}.
471     If \var{reduce} is set to \True the projection will be returned as a
472     \ReducedSolutionFS \Data object.
473     Otherwise the \SolutionFS representation is returned.
474     If \var{reduce} is set to \True lumping is used when the \eqn{PROJ.1} is
475     solved, otherwise the standard PDE solver is used.
476     Notice, that lumping requires significantly less computation time and memory.
477     The class is callable.
478 gross 2864 \end{classdesc}
479    
480     \begin{methoddesc}[Projector]{getSolverOptions}{}
481 caltinay 3316 returns the solver options for solving the PDE. In fact, the method returns
482     a \SolverOptions class object which can be used to modify the tolerance,
483     the solver or the preconditioner, see \Sec{SEC Solver Options} for details.
484 gross 2864 \end{methoddesc}
485    
486     \begin{methoddesc}[Projector]{getValue}{input_data}
487 caltinay 3316 projects the \var{input_data}. This method is equivalent to call an instance
488     of the class with argument \var{input_data}
489 gross 2864 \end{methoddesc}
490    
491 gross 2474 % \section{Transport Problems}
492     % \label{SEC Transport}
493 acodd 6927 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
494     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
495     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
496 gross 2474 \section{Solver Options}
497     \label{SEC Solver Options}
498    
499     \begin{classdesc}{SolverOptions}{}
500     This class defines the solver options for a linear or non-linear solver.
501 caltinay 3316 The option also supports the handling of diagnostic information.
502 gross 2474 \end{classdesc}
503    
504     \begin{methoddesc}[SolverOptions]{getSummary}{}
505 caltinay 3316 returns a string reporting the current settings.
506 gross 2474 \end{methoddesc}
507    
508     \begin{methoddesc}[SolverOptions]{getName}{key}
509 caltinay 3316 returns the name as a string of a given key.
510 gross 2474 \end{methoddesc}
511    
512 caltinay 5298 \begin{methoddesc}[SolverOptions]{setSolverMethod}{method}
513 caltinay 3316 sets the solver method to be used.
514     Use \var{method}=\member{SolverOptions.DIRECT} to indicate that a direct
515     rather than an iterative solver should be used and use
516     \var{method}=\member{SolverOptions.ITERATIVE} to indicate that an iterative
517 jduplessis 5673 rather than a direct solver should be used. Note that SolverOptions needs to be
518     imported from linearPDEs and is not the same as the object returned by pde.getSolverOptions().
519 jfenwick 3301 The value of \var{method} must be one of the constants:\\
520 caltinay 5298 \member{SolverOptions.DEFAULT} -- use default solver depending on other options\\
521     \member{SolverOptions.BICGSTAB} -- Biconjugate Gradient Stabilized iterative method\\
522     \member{SolverOptions.CGLS} -- Conjugate Gradient with Least Squares method\\
523     \member{SolverOptions.CGS} -- Conjugate Gradient Square method\\
524     \member{SolverOptions.CHOLEVSKY} -- Direct solver based on LDLT factorization\\
525     \member{SolverOptions.CR} -- Conjugate Residual method\\
526 acodd 6927 \member{SolverOptions.DIRECT} -- use a direct solver if available\\
527     %\member{Solver.Options.DIRECT_MUMPS}--runtime error\\
528     %\member{SolverOptions.DIRECT_PARDISO}--runtime error\\
529     \member{SolverOptions.DIRECT_SUPERLU} -- use a direct SUPERLU solver\\
530 acodd 6928 \member{SolverOptions.DIRECT_TRILINOS} -- use default TRILINOS default solver (KLU2) (chapter \ref{TRILINOS})\\
531 caltinay 5298 \member{SolverOptions.GMRES} -- Gram-Schmidt minimum residual method\\
532 acodd 6927 \member{SolverOptions.HRZ_LUMPING} -- Matrix lumping using the HRZ approach (section \ref{WAVE CHAP})\\
533     \member{SolverOptions.ITERATIVE} -- use a suitable iterative solver\\
534 caltinay 5298 \member{SolverOptions.LSQR} -- Least squares based LSQR solver\\
535 acodd 6927 \member{SolverOptions.LUMPING} -- Matrix lumping\\
536 caltinay 5298 \member{SolverOptions.MINRES} -- Minimum Residual method\\
537     \member{SolverOptions.NONLINEAR_GMRES} -- restarted GMRES for nonlinear systems\\
538     \member{SolverOptions.PCG} -- Preconditioned Conjugate Gradient method\\
539     \member{SolverOptions.PRES20} -- GMRES with restart after 20 steps and truncations after 5 residuals\\
540 acodd 6927 \member{SolverOptions.ROWSUM_LUMPING} -- Matrix lumping using row sum\\
541 caltinay 5298 \member{SolverOptions.TFQMR} -- Transpose Free Quasi Minimum Residual method.\\
542 caltinay 3316 Not all packages support all solvers. It can be assumed that a package makes a
543     reasonable choice if it encounters an unknown solver.
544     See Table~\ref{TAB FINLEY SOLVER OPTIONS 1} for the solvers supported by
545     \finley.
546 gross 2474 \end{methoddesc}
547    
548     \begin{methoddesc}[SolverOptions]{getSolverMethod}{}
549 caltinay 3316 returns the key of the solver method to be used.
550 gross 2474 \end{methoddesc}
551    
552 caltinay 5298 \begin{methoddesc}[SolverOptions]{setPreconditioner}{preconditioner}
553 caltinay 3316 sets the preconditioner to be used.
554 jfenwick 3301 The value of \var{preconditioner} must be one of the constants:\\
555 caltinay 5298 \member{SolverOptions.AMG} -- Algebraic Multi Grid\\
556 acodd 6927 %\member{SolverOptions.AMLI} -- Algebraic Multi Level Iteration\\
557 caltinay 5298 \member{SolverOptions.GAUSS_SEIDEL} -- Gauss-Seidel\\
558     \member{SolverOptions.ILU0} -- Incomplete LU-factorization with no fill-in\\
559     \member{SolverOptions.ILUT} -- Incomplete LU-factorization with fill-in\\
560     \member{SolverOptions.JACOBI} -- Jacobi preconditioner\\
561     \member{SolverOptions.NO_PRECONDITIONER} -- do not apply a preconditioner\\
562 acodd 6927 %\member{SolverOptions.REC_ILU} -- recursive ILU0\\
563 caltinay 5298 \member{SolverOptions.RILU} -- relaxed ILU0.\\
564 caltinay 3316 Not all packages support all preconditioners. It can be assumed that a package
565     makes a reasonable choice if it encounters an unknown preconditioner.
566     See Table~\ref{TAB FINLEY SOLVER OPTIONS 2} for the preconditioners supported
567     by \finley.
568 gross 2474 \end{methoddesc}
569    
570     \begin{methoddesc}[SolverOptions]{getPreconditioner}{}
571 caltinay 3316 returns the key of the preconditioner to be used.
572 gross 2474 \end{methoddesc}
573    
574 caltinay 5298 \begin{methoddesc}[SolverOptions]{setPackage}{package}
575 caltinay 3316 sets the solver package to be used as a solver.
576 caltinay 5298 The value of \var{package} must be one of the constants:\\
577     \member{SolverOptions.DEFAULT} -- choose a default depending on other options\\
578     \member{SolverOptions.CUSP} -- CUDA sparse linear algebra package\\
579     \member{SolverOptions.MKL} -- Intel MKL direct solver\\
580     \member{SolverOptions.PASO} -- built-in PASO solver library\\
581 acodd 6928 \member{SolverOptions.TRILINOS} -- Trilinos solver package (chapter \ref{TRILINOS})\\
582 caltinay 5298 \member{SolverOptions.UMFPACK} -- direct solver from the UMFPACK library.\\
583 caltinay 3316 Not all packages are supported on all implementations. An exception may be
584     thrown on some platforms if a particular package is requested.
585     Currently \finley supports \member{SolverOptions.PASO} (as default) and, if
586     available, \member{SolverOptions.MKL}\footnote{If the stiffness matrix is
587     non-regular \MKL may return without returning a proper error code.
588 caltinay 5298 If you observe suspicious solutions when using MKL, this may be caused by a
589 caltinay 3316 non-invertible operator.} and \member{SolverOptions.UMFPACK}.
590 gross 2474 \end{methoddesc}
591    
592     \begin{methoddesc}[SolverOptions]{getPackage}{}
593 caltinay 3316 returns the solver package key.
594 gross 2474 \end{methoddesc}
595    
596 acodd 6927 \begin{methoddesc}[SolverOptions]{setTrilinosParameter}{\optional{ name , value}}
597     sets Trilinos parameters for use by MueLu and Trilinos iterative and direct solvers. It is important that the exact space between words is included in the names.
598     The following keywords are supported:\\
599     \var{"verbosity"}: controls level of AMG output,
600     \var{"none"}, \var{"low"}, \var{"medium"}, \var{"high"}, and \var{"extreme"}\\
601     %\var{"print initial parameters"}: \var{True}
602     \var{"problem:type"}: \var{"unknown"}, \var{"Poisson-2D"}, \var{"Poisson-3D"}, \var{"Elasticity-2D"},\\ \hspace{3.2cm}\var{"Elasticity-3D"}, \var{"Poisson-2D-complex"}, \var{"Poisson-3D-complex"},\\ \hspace{3.2cm}\var{"Elasticity-2D-complex"}, \var{"Elasticity-3D-complex"},\\
603     \hspace{3.2cm}\var{"ConvectionDiffusion"} and \var{"MHD"}.
604     \\
605     \var{"number~of~equations"}: number of equations\\
606     \var{"multigrid~algorithm"}: \var{ "sa"}, \var{"unsmoothed"}, \var{ "pg"}, \var{"interp"}, \var{"emin"},\\ \hspace{4.2cm}\var{"semicoarsen"}\\
607     \var{"sa:~damping factor"}: for smoothed aggregation AMG alorithm, default =1.3\\
608     \var{"sa:~use~filtered~matrix"}: Booleon\\
609     \var{"filtered~matrix:~use~lumping"}: Boolean\\
610     \var{"filtered~matrix:~reuse~eigenvalue"}: Boolean\\
611     \var{"interp:~interpolation~order"}: 0,~1\\
612     \var{"interp:~build~coarse~coordinates}: Boolean\\
613     \var{"emin:~iterative~method"}: \var{"cg"}, \var{"gmres"} or \var{"sd"}\\
614     \var{"emin:~num~iterations"}: integer\\
615     \var{"emin:~num~reuse~iterations"}: integer\\
616     %options.setTrilinosParameter("emin: pattern", "AkPtent")
617     %options.setTrilinosParameter("emin: pattern order", 1)
618     %# semicoarsen
619     %options.setTrilinosParameter("semicoarsen: coarsen rate", 3)
620     %#
621     %options.setTrilinosParameter("transpose: use implicit", False)
622     %options.setTrilinosParameter("max levels", 10)
623     %options.setTrilinosParameter("coarse: max size", 2000)
624     %options.setTrilinosParameter("coarse: type", "SuperLU")
625     %options.setTrilinosParameter("aggregation: type", "structured")
626     %options.setTrilinosParameter("aggregation: ordering", "natural")
627     % # "natural", "graph", "random"
628     %options.setTrilinosParameter("aggregation: drop scheme", "classical")
629     % # "classical", "distance laplacian"
630     %options.setTrilinosParameter("aggregation: drop tol", 0.0)
631     %options.setTrilinosParameter("aggregation: min agg size", 2)
632     %options.setTrilinosParameter("aggregation: max agg size", -1)
633     % # -1 means unlimited
634     %options.setTrilinosParameter("aggregation: Dirichlet threshold", 1e-5)
635     %options.setTrilinosParameter("problem: symmetric", True)
636     %options.setTrilinosParameter("smoother: pre or post", "both")
637     %options.setTrilinosParameter("smoother: type", "RELAXATION")
638     %options.setTrilinosParameter("smoother: pre type", "CHEBYSHEV")
639     %options.setTrilinosParameter("smoother: post type", "RELAXATION")
640     \var{"cycle~type"}: \var{"V"} or \var{"W"}\\
641     %options.setTrilinosParameter("reuse: type", "full")
642     %options.setTrilinosParameter("repartition: enable", False)
643     %options.setTrilinosParameter("repartition: start level", 2)
644     %options.setTrilinosParameter("repartition: min rows per proc", 800)
645     %options.setTrilinosParameter("repartition: max imbalance", 1.2)
646     %options.setTrilinosParameter("repartition: remap parts", True)
647     %options.setTrilinosParameter("repartition: rebalance P and R", False)
648     \var{"xml~parameter~file"}: name of XML file containing chosen XML parameters\\
649 caltinay 5298 \end{methoddesc}
650    
651 gross 2474 \begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}}
652 caltinay 3316 resets the diagnostics. If \var{all} is \True all diagnostics, including
653     accumulative counters, are reset.
654 gross 2474 \end{methoddesc}
655    
656     \begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}}
657 caltinay 3316 returns the diagnostic information \var{name}. The following keywords are
658     supported:\\
659     \var{"num_iter"}: number of iteration steps\\
660     \var{"cum_num_iter"}: cumulative number of iteration steps\\
661     \var{"num_level"}: number of levels in the multi level solver\\
662     \var{"num_inner_iter"}: number of inner iteration steps\\
663     \var{"cum_num_inner_iter"}: cumulative number of inner iteration steps\\
664     \var{"time"}: execution time\\
665     \var{"cum_time"}: cumulative execution time\\
666     \var{"set_up_time"}: time to set up the solver, typically this includes
667     factorization and reordering\\
668     \var{"cum_set_up_time"}: cumulative time to set up the solver\\
669     \var{"net_time"}: net execution time, excluding setup time for the solver
670     and execution time for preconditioner\\
671     \var{"cum_net_time"}: cumulative net execution time\\
672     \var{"residual_norm"}: norm of the final residual\\
673     \var{"converged"}: status of convergence\\
674 gross 3402 \var{"preconditioner_size"}: size of preconditioner in MBytes \\
675 caltinay 4891 \var{"time_step_backtracking_used"}: whether the time step size was reduced after convergence failure \\
676     \var{"coarse_level_sparsity"}: the sparsity at coarse level (AMG only) \\
677     \var{"num_coarse_unknowns"}: number of unknowns at coarse level (AMG only) .
678 gross 3402
679 gross 2474 \end{methoddesc}
680    
681     \begin{methoddesc}[SolverOptions]{hasConverged}{}
682 caltinay 3316 returns \True if the last solver call has been finalized successfully.
683 gross 2474 If an exception has been thrown by the solver the status of this flag is undefined.
684     \end{methoddesc}
685    
686    
687 caltinay 5298 \begin{methoddesc}[SolverOptions]{setReordering}{ordering}
688 caltinay 3316 sets the key of the reordering method to be applied if supported by the solver.
689     Some direct solvers support reordering to optimize compute time and storage
690     use during elimination. The value of \var{ordering} must be one of the
691     constants:\\
692 caltinay 5298 \member{SolverOptions.DEFAULT_REORDERING} -- as recommended by the solver\\
693     \member{SolverOptions.MINIMUM_FILL_IN} -- reorder matrix to reduce fill-in during factorization\\
694     \member{SolverOptions.NESTED_DISSECTION} -- reorder matrix to improve load balancing during factorization\\
695     \member{SolverOptions.NO_REORDERING} -- no matrix reordering applied.
696 gross 2474 \end{methoddesc}
697    
698     \begin{methoddesc}[SolverOptions]{getReordering}{}
699 caltinay 3316 returns the key of the reordering method to be applied if supported by the solver.
700 gross 2474 \end{methoddesc}
701    
702     \begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}}
703 caltinay 3316 sets the number of iterations steps after which \GMRES is to perform a restart.
704 gross 2474 If \var{restart} is equal to \var{None} no restart is performed.
705     \end{methoddesc}
706    
707     \begin{methoddesc}[SolverOptions]{getRestart}{}
708 caltinay 3316 returns the number of iterations steps after which \GMRES performs a restart.
709 gross 2474 \end{methoddesc}
710    
711     \begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}}
712 gross 3567 sets the number of residuals in \GMRES to be stored for orthogonalization.
713     The more residuals are stored the faster \GMRES converges but the higher the storage needs are and the more expensive
714     a single iteration step becomes.
715 gross 2474 \end{methoddesc}
716    
717     \begin{methoddesc}[SolverOptions]{getTruncation}{}
718 caltinay 3316 returns the number of residuals in \GMRES to be stored for orthogonalization.
719 gross 2474 \end{methoddesc}
720    
721    
722     \begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}}
723 caltinay 3316 sets the maximum number of iteration steps.
724 gross 2474 \end{methoddesc}
725    
726     \begin{methoddesc}[SolverOptions]{getIterMax}{}
727 caltinay 3316 returns maximum number of iteration steps.
728 gross 2474 \end{methoddesc}
729    
730 acodd 6927 %\begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}}
731     %sets the maximum number of coarsening levels to be used in the \AMG solver or
732     %preconditioner.
733     %\end{methoddesc}
734 gross 2474
735 acodd 6927 %\begin{methoddesc}[SolverOptions]{getLevelMax}{}
736     %returns the maximum number of coarsening levels to be used in an algebraic
737     %multi level solver or preconditioner.
738     %\end{methoddesc}
739 gross 2474
740 acodd 6927 %\begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.25}}
741     %sets the threshold for coarsening in the \AMG solver or preconditioner.
742     %\end{methoddesc}
743 gross 2474
744 acodd 6927 %\begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{}
745     %returns the threshold for coarsening in the \AMG solver or preconditioner.
746     %\end{methoddesc}
747 gross 2474
748 acodd 6927 %\begin{methoddesc}[SolverOptions]{setDiagonalDominanceThreshold}{\optional{value=0.5}}
749     %sets the threshold for diagonal dominant rows which are eliminated during \AMG coarsening.
750     %\end{methoddesc}
751 gross 3402
752 acodd 6927 %\begin{methoddesc}[SolverOptions]{getDiagonalDominanceThreshold}{}
753     %returns the threshold for diagonal dominant rows which are eliminated during \AMG coarsening.
754     %\end{methoddesc}
755 gross 3402
756 acodd 6927 %\begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}}
757     %sets the minimum size of the coarsest level matrix in \AMG.
758     %\end{methoddesc}
759 artak 2524
760 acodd 6927 %\begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{}
761     %returns the minimum size of the coarsest level matrix in \AMG.
762     %\end{methoddesc}
763 artak 2524
764 acodd 6927 %\begin{methoddesc}[SolverOptions]{setSmoother}{\optional{smoother=\GAUSSSEIDEL}}
765     %sets the \JACOBI or \GAUSSSEIDEL smoother to be used with \AMG.
766     %\end{methoddesc}
767 artak 2976
768 acodd 6927 %\begin{methoddesc}[SolverOptions]{getSmoother}{}
769     %returns the key of the smoother used in \AMG.
770     %\end{methoddesc}
771 artak 2976
772 acodd 6927 %\begin{methoddesc}[SolverOptions]{setAMGInterpolation}{\optional{method=\var{None}}}
773     %sets interpolation method for \AMG to
774     %\member{CLASSIC_INTERPOLATION_WITH_FF_COUPLING},
775     %\member{CLASSIC_INTERPOLATION}, or
776     %\member{DIRECT_INTERPOLATION}.
777     %\end{methoddesc}
778 gross 3439
779 acodd 6927 %\begin{methoddesc}[SolverOptions]{getAMGInterpolation}{}
780     %returns the key of the interpolation method for \AMG.
781     %\end{methoddesc}
782 gross 3439
783 acodd 6927 %\begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}}
784     %sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
785     %\end{methoddesc}
786 gross 2474
787 acodd 6927 %\begin{methoddesc}[SolverOptions]{getNumSweeps}{}
788     %returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
789     %\end{methoddesc}
790 gross 2474
791 acodd 6927 %\begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}}
792     %sets the number of sweeps in the pre-smoothing step of \AMG.
793     %\end{methoddesc}
794 gross 2474
795 acodd 6927 %\begin{methoddesc}[SolverOptions]{getNumPreSweeps}{}
796     %returns the number of sweeps in the pre-smoothing step of \AMG.
797     %\end{methoddesc}
798 gross 2474
799 acodd 6927 %\begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}}
800     %sets the number of sweeps in the post-smoothing step of \AMG.
801     %\end{methoddesc}
802 gross 2474
803 acodd 6927 %\begin{methoddesc}[SolverOptions]{getNumPostSweeps}{}
804     %returns he number of sweeps in the post-smoothing step of \AMG.
805     %\end{methoddesc}
806 gross 2474
807     \begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}}
808 caltinay 3316 sets the relative tolerance for the solver. The actual meaning of tolerance
809     depends on the underlying PDE library. In most cases, the tolerance
810 gross 2474 will only consider the error from solving the discrete problem but will
811     not consider any discretization error.
812     \end{methoddesc}
813    
814     \begin{methoddesc}[SolverOptions]{getTolerance}{}
815 caltinay 3316 returns the relative tolerance for the solver.
816 gross 2474 \end{methoddesc}
817    
818     \begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}}
819 caltinay 3316 sets the absolute tolerance for the solver. The actual meaning of tolerance
820     depends on the underlying PDE library. In most cases, the tolerance
821 gross 2474 will only consider the error from solving the discrete problem but will
822     not consider any discretization error.
823     \end{methoddesc}
824    
825     \begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{}
826 caltinay 3316 returns the absolute tolerance for the solver.
827 gross 2474 \end{methoddesc}
828    
829     \begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}}
830 caltinay 3316 sets the relative tolerance for an inner iteration scheme, for instance
831 gross 2474 on the coarsest level in a multi-level scheme.
832     \end{methoddesc}
833    
834     \begin{methoddesc}[SolverOptions]{getInnerTolerance}{}
835 caltinay 3316 returns the relative tolerance for an inner iteration scheme.
836 gross 2474 \end{methoddesc}
837    
838     \begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}}
839 caltinay 3316 sets the relaxation factor used to add dropped elements in \RILU to the main diagonal.
840 gross 2474 \end{methoddesc}
841    
842     \begin{methoddesc}[SolverOptions]{getRelaxationFactor}{}
843 caltinay 3316 returns the relaxation factor used to add dropped elements in \RILU to the main diagonal.
844 gross 2474 \end{methoddesc}
845    
846     \begin{methoddesc}[SolverOptions]{isSymmetric}{}
847 caltinay 3316 returns \True if the discrete system is indicated as symmetric.
848 gross 2474 \end{methoddesc}
849    
850     \begin{methoddesc}[SolverOptions]{setSymmetryOn}{}
851 caltinay 3316 sets the symmetry flag to indicate that the coefficient matrix is symmetric.
852 gross 2474 \end{methoddesc}
853    
854     \begin{methoddesc}[SolverOptions]{setSymmetryOff}{}
855 caltinay 3316 clears the symmetry flag for the coefficient matrix.
856 gross 2474 \end{methoddesc}
857    
858     \begin{methoddesc}[SolverOptions]{isVerbose}{}
859 caltinay 3316 returns \True if the solver is expected to be verbose.
860 gross 2474 \end{methoddesc}
861    
862     \begin{methoddesc}[SolverOptions]{setVerbosityOn}{}
863 caltinay 3316 switches the verbosity of the solver on.
864 gross 2474 \end{methoddesc}
865    
866     \begin{methoddesc}[SolverOptions]{setVerbosityOff}{}
867 caltinay 3316 switches the verbosity of the solver off.
868 gross 2474 \end{methoddesc}
869    
870     \begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{}
871 caltinay 3316 returns \True if the tolerance of the inner solver is selected automatically.
872 gross 2474 Otherwise the inner tolerance set by \member{setInnerTolerance} is used.
873     \end{methoddesc}
874    
875     \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{}
876 caltinay 3316 switches the automatic selection of inner tolerance on.
877 gross 2474 \end{methoddesc}
878    
879     \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{}
880 caltinay 3316 switches the automatic selection of inner tolerance off.
881 gross 2474 \end{methoddesc}
882    
883     \begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}}
884 caltinay 3316 sets the maximum number of iteration steps for the inner iteration.
885 gross 2474 \end{methoddesc}
886    
887     \begin{methoddesc}[SolverOptions]{getInnerIterMax}{}
888 caltinay 3316 returns the maximum number of inner iteration steps.
889 gross 2474 \end{methoddesc}
890    
891     \begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{}
892 caltinay 3316 returns \True if a failure to meet the stopping criteria within the given
893     number of iteration steps is not raising in exception. This is useful
894     if a solver is used in a non-linear context where the non-linear solver can
895     continue even if the returned solution does not necessarily meet the stopping
896     criteria. One can use the \member{hasConverged} method to check if the
897 gross 2474 last call to the solver was successful.
898     \end{methoddesc}
899    
900     \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{}
901 caltinay 3316 switches the acceptance of a failure of convergence on.
902 gross 2474 \end{methoddesc}
903    
904     \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{}
905 caltinay 3316 switches the acceptance of a failure of convergence off.
906 gross 2474 \end{methoddesc}
907    
908     \begin{memberdesc}[SolverOptions]{DEFAULT}
909 caltinay 3316 default method, preconditioner or package to be used to solve the PDE.
910     An appropriate method should be chosen by the used PDE solver library.
911 gross 625 \end{memberdesc}
912 jgs 102
913 gross 2474 \begin{memberdesc}[SolverOptions]{MKL}
914 caltinay 3316 the \MKL library by Intel, \Ref{MKL}\footnote{The \MKL library will only be
915     available when the Intel compilation environment was used to build \escript.}.
916 gross 625 \end{memberdesc}
917 jgs 102
918 gross 2474 \begin{memberdesc}[SolverOptions]{UMFPACK}
919 caltinay 3316 the \UMFPACK library, \Ref{UMFPACK}. Note that \UMFPACK is not parallelized.
920 gross 625 \end{memberdesc}
921 jgs 102
922 gross 2474 \begin{memberdesc}[SolverOptions]{PASO}
923 caltinay 5295 \PASO is the default solver library of \finley, see \Sec{chap:finley}.
924 gross 625 \end{memberdesc}
925 jgs 102
926 gross 2474 \begin{memberdesc}[SolverOptions]{ITERATIVE}
927 caltinay 3316 the default iterative method and preconditioner. The actual method used
928     depends on the PDE solver library and the chosen solver package.
929     Typically, \PCG is used for symmetric PDEs and \BiCGStab otherwise, both with
930     \JACOBI preconditioner.
931 gross 625 \end{memberdesc}
932 jgs 102
933 gross 2474 \begin{memberdesc}[SolverOptions]{DIRECT}
934 gross 660 the default direct linear solver.
935 gross 625 \end{memberdesc}
936 jgs 102
937 gross 2474 \begin{memberdesc}[SolverOptions]{CHOLEVSKY}
938 caltinay 3316 direct solver based on Cholevsky factorization (or similar), see \Ref{Saad}.
939     The solver requires a symmetric PDE.
940 gross 625 \end{memberdesc}
941 jgs 110
942 gross 2474 \begin{memberdesc}[SolverOptions]{PCG}
943 caltinay 3316 preconditioned conjugate gradient method, see \Ref{WEISS}\index{linear solver!PCG}\index{PCG}.
944     The solver requires a symmetric PDE.
945 gross 625 \end{memberdesc}
946 jgs 110
947 gross 2474 \begin{memberdesc}[SolverOptions]{TFQMR}
948 caltinay 3316 transpose-free quasi-minimal residual method, see \Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}.
949     \end{memberdesc}
950 artak 1978
951 gross 2474 \begin{memberdesc}[SolverOptions]{GMRES}
952 caltinay 3316 the GMRES method, see \Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}.
953 caltinay 3331 Truncation and restart are controlled by the \var{truncation} and \var{restart}
954     parameters of \method{getSolution}.
955 gross 625 \end{memberdesc}
956 jgs 102
957 gross 2474 \begin{memberdesc}[SolverOptions]{MINRES}
958 caltinay 3316 minimal residual method\index{linear solver!MINRES}\index{MINRES}
959     \end{memberdesc}
960 artak 1978
961 gross 3379 \begin{memberdesc}[SolverOptions]{ROWSUM_LUMPING}
962 gross 4052 row sum lumping of the stiffness matrix, see Section~\ref{LUMPING} for details\index{linear solver!row sum lumping}\index{row sum lumping}.
963 gross 660 Lumping does not use the linear system solver library.
964 gross 625 \end{memberdesc}
965 jgs 107
966 gross 3379 \begin{memberdesc}[SolverOptions]{HRZ_LUMPING}
967 gross 4052 HRZ lumping of the stiffness matrix, see Section~\ref{LUMPING} for details\index{linear solver!HRZ lumping}\index{HRZ lumping}.
968 gross 3379 Lumping does not use the linear system solver library.
969     \end{memberdesc}
970    
971 gross 2474 \begin{memberdesc}[SolverOptions]{PRES20}
972 caltinay 3316 the GMRES method with truncation after five residuals and restart after
973     20 steps, see \Ref{WEISS}.
974 gross 999 \end{memberdesc}
975 gross 625
976 gross 2474 \begin{memberdesc}[SolverOptions]{CGS}
977 caltinay 3316 conjugate gradient squared method, see \Ref{WEISS}.
978 jgs 107 \end{memberdesc}
979    
980 gross 2474 \begin{memberdesc}[SolverOptions]{BICGSTAB}
981 caltinay 3316 stabilized bi-conjugate gradients methods, see \Ref{WEISS}.
982 jgs 107 \end{memberdesc}
983    
984 gross 2474 \begin{memberdesc}[SolverOptions]{SSOR}
985 caltinay 3316 symmetric successive over-relaxation method, see \Ref{WEISS}.
986     Typically used as preconditioner but some linear solver libraries support
987 gross 660 this as a solver.
988 gross 625 \end{memberdesc}
989 gross 2474
990     \begin{memberdesc}[SolverOptions]{ILU0}
991 caltinay 3316 the incomplete LU factorization preconditioner with no fill-in, see \Ref{Saad}.
992 gross 653 \end{memberdesc}
993    
994 gross 2474 \begin{memberdesc}[SolverOptions]{JACOBI}
995 caltinay 3316 the Jacobi preconditioner, see \Ref{Saad}.
996 gross 653 \end{memberdesc}
997    
998 gross 2474 \begin{memberdesc}[SolverOptions]{AMG}
999 caltinay 3316 the algebraic multi grid method, see \Ref{AMG}. This method can be used as
1000     linear solver method but is more robust when used as a preconditioner.
1001 gross 653 \end{memberdesc}
1002    
1003 gross 2474 \begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL}
1004 caltinay 3316 the symmetric Gauss-Seidel preconditioner, see \Ref{Saad}.
1005 gross 2474 \member{getNumSweeps()} is the number of sweeps used.
1006 artak 1978 \end{memberdesc}
1007    
1008 gross 3571 %\begin{memberdesc}[SolverOptions]{RILU}
1009     %relaxed incomplete LU factorization preconditioner, see \Ref{RELAXILU}.
1010     %This method is similar to the one used for \ILU but dropped elements are added
1011     %to the main diagonal with the relaxation factor \member{getRelaxationFactor}.
1012     %\end{memberdesc}
1013 jgs 107
1014 gross 2474 \begin{memberdesc}[SolverOptions]{REC_ILU}
1015 caltinay 3316 recursive incomplete LU factorization preconditioner, see \Ref{RILU}.
1016     This method is similar to the one used for \ILU but applies reordering during
1017     the factorization.
1018 gross 2474 \end{memberdesc}
1019    
1020     \begin{memberdesc}[SolverOptions]{NO_REORDERING}
1021 caltinay 3316 no reordering is used during factorization.
1022 gross 653 \end{memberdesc}
1023 gross 625
1024 gross 2474 \begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING}
1025     the default reordering method during factorization.
1026     \end{memberdesc}
1027    
1028     \begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN}
1029 caltinay 3316 applies reordering before factorization using a fill-in minimization strategy.
1030     You have to check with the particular solver library or linear solver package
1031     if this is supported. In any case, it is advisable to apply reordering on the
1032     mesh to minimize fill-in.
1033 gross 653 \end{memberdesc}
1034 gross 625
1035 gross 2474 \begin{memberdesc}[SolverOptions]{NESTED_DISSECTION}
1036 caltinay 3316 applies reordering before factorization using a nested dissection strategy.
1037     You have to check with the particular solver library or linear solver package
1038     if this is supported. In any case, it is advisable to apply reordering on the
1039     mesh to minimize fill-in.
1040 gross 653 \end{memberdesc}
1041 gross 625
1042 caltinay 6318 \begin{memberdesc}[SolverOptions]{TRILINOS}
1043     the Trilinos library~\cite{Trilinos} is used as a solver.
1044 gross 2474 \end{memberdesc}
1045 gross 625
1046 gross 2474 \begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER}
1047     no preconditioner is applied.
1048     \end{memberdesc}
1049    
1050 gross 3439 \begin{memberdesc}[SolverOptions]{DIRECT_INTERPOLATION}
1051     direct interpolation in \AMG, see \cite{AMG}
1052     \end{memberdesc}
1053     \begin{memberdesc}[SolverOptions]{CLASSIC_INTERPOLATION}
1054     classic interpolation in \AMG, see \cite{AMG}
1055     \end{memberdesc}
1056     \begin{memberdesc}[SolverOptions]{CLASSIC_INTERPOLATION_WITH_FF_COUPLING}
1057 caltinay 4286 classic interpolation with enforced FF coupling in \AMG, see \cite{AMG}
1058 gross 3439 \end{memberdesc}
1059    
1060 gross 3379 \input{lumping}

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26