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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4286 - (hide annotations)
Thu Mar 7 04:28:11 2013 UTC (6 years, 6 months ago) by caltinay
File MIME type: application/x-tex
File size: 40893 byte(s)
Assorted spelling fixes.

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