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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2651 - (show annotations)
Mon Sep 7 03:39:45 2009 UTC (11 years, 6 months ago) by jfenwick
File MIME type: application/x-tex
File size: 37905 byte(s)
Fixed latex compile error.
Fixed some overful hboxes

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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26