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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2559 - (show annotations)
Mon Jul 27 05:19:21 2009 UTC (10 years, 2 months ago) by artak
File MIME type: application/x-tex
File size: 37682 byte(s)
typo: MaxIter changed IterMax
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 'Residual norm of returned solution =', mypde.getDiagnostics('residual_norm')
156 \end{python}
157 Typically a negative value for a diagnostic value indicates that the value is undefined.
158
159 \subsection{Classes}
160 \declaremodule{extension}{esys.escript.linearPDEs}
161 \modulesynopsis{Linear partial differential equation handler}
162 The module \linearPDEs provides an interface to define and solve linear partial
163 differential equations within \escript. The module \linearPDEs does not provide any
164 solver capabilities in itself but hands the PDE over to
165 the PDE solver library defined through the \Domain of the PDE, eg. \finley.
166 The general interface is provided through the \LinearPDE class. The \Poisson
167 class which is also derived form the \LinearPDE class should be used
168 to define the Poisson equation \index{Poisson}.
169
170 \subsection{\LinearPDE class}
171 This is the general class to define a linear PDE in \escript. We list a selection of the most
172 important methods of the class. For a complete list, see the reference at \ReferenceGuide.
173
174 \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
175 opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}
176 and \var{numSolutions} gives the number of equations and the number of solution components.
177 If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations
178 and the number solutions, respectively, stay undefined until a coefficient is
179 defined.
180 \end{classdesc}
181
182 \subsubsection{\LinearPDE methods}
183
184 \begin{methoddesc}[LinearPDE]{setValue}{
185 \optional{A}\optional{, B},
186 \optional{, C}\optional{, D}
187 \optional{, X}\optional{, Y}
188 \optional{, d}\optional{, y}
189 \optional{, d_contact}\optional{, y_contact}
190 \optional{, q}\optional{, r}}
191 assigns new values to coefficients. By default all values are assumed to be zero\footnote{
192 In fact it is assumed they are not present by assigning the value \code{escript.Data()}. The
193 can by used by the solver library to reduce computational costs.
194 }
195 If the new coefficient value is not a \Data object, it is converted into a \Data object in the
196 appropriate \FunctionSpace.
197 \end{methoddesc}
198
199 \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
200 return the value assigned to coefficient \var{name}. If \var{name} is not a valid name
201 an exception is raised.
202 \end{methoddesc}
203
204 \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
205 returns the shape of coefficient \var{name} even if no value has been assigned to it.
206 \end{methoddesc}
207
208 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
209 returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.
210 \end{methoddesc}
211
212 \begin{methoddesc}[LinearPDE]{setDebugOn}{}
213 switches on debug mode.
214 \end{methoddesc}
215
216 \begin{methoddesc}[LinearPDE]{setDebugOff}{}
217 switches off debug mode.
218 \end{methoddesc}
219
220 \begin{methoddesc}[LinearPDE]{getSolverOptions}{}
221 returns the solver options for solving the PDE. In fact the method returns
222 a \SolverOptions class object which can be used to modify the tolerance,
223 the solver or the preconditioner, see Section~\ref{SEC Solver Options} for details.
224 \end{methoddesc}
225
226 \begin{methoddesc}[LinearPDE]{setSolverOptions}{\optional{options=None}}
227 sets the solver options for solving the PDE. If argument \var{options} is present it
228 must be a \SolverOptions class object, see Section~\ref{SEC Solver Options} for details. Otherwise the solver options are reset to the default.
229 \end{methoddesc}
230
231
232 \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
233 returns \True if \LUMPING is set as the solver for the system of linear equations.
234 Otherwise \False is returned.
235 \end{methoddesc}
236
237
238 \begin{methoddesc}[LinearPDE]{getDomain}{}
239 returns the \Domain of the PDE.
240 \end{methoddesc}
241
242 \begin{methoddesc}[LinearPDE]{getDim}{}
243 returns the spatial dimension of the PDE.
244 \end{methoddesc}
245
246 \begin{methoddesc}[LinearPDE]{getNumEquations}{}
247 returns the number of equations.
248 \end{methoddesc}
249
250 \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
251 returns the number of components of the solution.
252 \end{methoddesc}
253
254 \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
255 returns \True if the PDE is symmetric and \False otherwise.
256 The method is very computationally expensive and should only be
257 called for testing purposes. The symmetry flag is not altered.
258 If \var{verbose}=\True information about where symmetry is violated
259 are printed.
260 \end{methoddesc}
261
262 \begin{methoddesc}[LinearPDE]{getFlux}{u}
263 returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}
264 defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
265 \end{methoddesc}
266
267
268 \begin{methoddesc}[LinearPDE]{isSymmetric}{}
269 returns \True if the PDE has been indicated to be symmetric.
270 Otherwise \False is returned.
271 \end{methoddesc}
272
273 \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
274 indicates that the PDE is symmetric.
275 \end{methoddesc}
276
277 \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
278 indicates that the PDE is not symmetric.
279 \end{methoddesc}
280
281 \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
282 switches on the reduction of polynomial order for the solution and equation evaluation even if
283 a quadratic or higher interpolation order is defined in the \Domain. This feature may not
284 be supported by all PDE libraries.
285 \end{methoddesc}
286
287 \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
288 switches off the reduction of polynomial order for the solution and
289 equation evaluation.
290 \end{methoddesc}
291
292 \begin{methoddesc}[LinearPDE]{getOperator}{}
293 returns the \Operator of the PDE.
294 \end{methoddesc}
295
296 \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
297 returns the right hand side of the PDE as a \Data object. If
298 \var{ignoreConstraint}=\True, then the constraints are not considered
299 when building up the right hand side.
300 \end{methoddesc}
301
302 \begin{methoddesc}[LinearPDE]{getSystem}{}
303 returns the \Operator and right hand side of the PDE.
304 \end{methoddesc}
305
306 \begin{methoddesc}[LinearPDE]{getSolution}{}
307 returns (an approximation of) the solution of the PDE. This call
308 will invoke the discretization of the PDE and the solution of the resulting
309 system of linear equations. Keep in mind that this call is typically computational
310 expensive and can - depending on the PDE and the discretiztion - take a long time to complete.
311 \end{methoddesc}
312
313
314
315 \subsection{The \Poisson Class}
316 The \Poisson class provides an easy way to define and solve the Poisson
317 equation
318 \begin{equation}\label{POISSON.1}
319 -u\hackscore{,ii}=f\; .
320 \end{equation}
321 with homogeneous boundary conditions
322 \begin{equation}\label{POISSON.2}
323 n\hackscore{i}u\hackscore{,i}=0
324 \end{equation}
325 and homogeneous constraints
326 \begin{equation}\label{POISSON.3}
327 u=0 \mbox{ where } q>0
328 \end{equation}
329 $f$ has to be a \Scalar in the \Function and $q$ must be
330 a \Scalar in the \SolutionFS.
331
332 \begin{classdesc}{Poisson}{domain}
333 opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
334 \end{classdesc}
335 \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
336 assigns new values to \var{f} and \var{q}.
337 \end{methoddesc}
338
339 \subsection{The \Helmholtz Class}
340 The \Helmholtz class defines the Helmholtz problem
341 \begin{equation}\label{HZ.1}
342 \omega \; u - (k\; u\hackscore{,j})\hackscore{,j} = f
343 \end{equation}
344 with natural boundary conditions
345 \begin{equation}\label{HZ.2}
346 k\; u\hackscore{,j} n\hackscore{,j} = g- \alpha \; u
347 \end{equation}
348 and constraints:
349 \begin{equation}\label{HZ.3}
350 u=r \mbox{ where } q>0
351 \end{equation}
352 $\omega$, $k$, $f$ have to be a \Scalar in the \Function,
353 $g$ and $\alpha$ must be a \Scalar in the \FunctionOnBoundary,
354 and $q$ and $r$ must be a \Scalar in the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
355
356 \begin{classdesc}{Helmholtz}{domain}
357 opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE.
358 \end{classdesc}
359 \begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}}
360 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.
361 \end{methoddesc}
362
363 \subsection{The \Lame Class}
364 The \Lame class defines a Lame equation problem:
365 \begin{equation}\label{LE.1}
366 -\mu (u\hackscore{i,j}+u\hackscore{j,i})+\lambda u\hackscore{k,k})\hackscore{j} = F\hackscore{i}-\sigma\hackscore{ij,j}
367 \end{equation}
368 with natural boundary conditions:
369 \begin{equation}\label{LE.2}
370 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}
371 \end{equation}
372 and constraint
373 \begin{equation}\label{LE.3}
374 u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
375 \end{equation}
376 $\mu$, $\lambda$ have to be a \Scalar in the \Function,
377 $F$ has to be a \Vector in the \Function,
378 $\sigma$ has to be a \Tensor in the \Function,
379 $f$ must be a \Vector in the \FunctionOnBoundary,
380 and $q$ and $r$ must be a \Vector in the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
381
382 \begin{classdesc}{Lame}{domain}
383 opens a Lame equation on the \Domain domain. \Lame is derived from \LinearPDE.
384 \end{classdesc}
385 \begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}}
386 assigns new values to
387 \var{lame_lambda},
388 \var{lame_mu},
389 \var{F},
390 \var{sigma},
391 \var{f},
392 \var{r} and
393 \var{q}
394 By default all values are set to be zero.
395 \end{methoddesc}
396
397 % \section{Transport Problems}
398 % \label{SEC Transport}
399
400 \section{Solver Options}
401 \label{SEC Solver Options}
402
403 \begin{classdesc}{SolverOptions}{}
404 This class defines the solver options for a linear or non-linear solver.
405 The option also supports the handling of diagnostic informations.
406 \end{classdesc}
407
408 \begin{methoddesc}[SolverOptions]{getSummary}{}
409 Returns a string reporting the current settings
410 \end{methoddesc}
411
412 \begin{methoddesc}[SolverOptions]{getName}{key}
413 Returns the name as a string of a given key
414 \end{methoddesc}
415
416 \begin{methoddesc}[SolverOptions]{setSolverMethod}{\optional{method=SolverOptions.DEFAULT}}
417 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.
418 The value of \var{method} must be one of the constants
419 \member{SolverOptions.DEFAULT}, \member{SolverOptions.DIRECT}, \member{SolverOptions.CHOLEVSKY}, \member{SolverOptions.PCG},\member{SolverOptions.CR}, \member{SolverOptions.CGS}, \member{SolverOptions.BICGSTAB}, \member{SolverOptions.SSOR},
420 \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},
421 or \member{SolverOptions.GAUSS_SEIDEL}.
422 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.
423 \end{methoddesc}
424
425 \begin{methoddesc}[SolverOptions]{getSolverMethod}{}
426 Returns key of the solver method to be used.
427 \end{methoddesc}
428
429 \begin{methoddesc}[SolverOptions]{setPreconditioner}{\optional{preconditioner=SolverOptions.JACOBI}}
430 Sets the preconditioner to be used.
431 The value of \var{preconditioner} must be one of the constants
432 \member{SolverOptions.SSOR}, \member{SolverOptions.ILU0}, \member{SolverOptions.ILUT}, \member{SolverOptions.JACOBI},
433 \member{SolverOptions.AMG}, \member{SolverOptions.REC_ILU}, \member{SolverOptions.GAUSS_SEIDEL}, \member{SolverOptions.RILU}, or
434 \member{SolverOptions.NO_PRECONDITIONER}.
435 Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters
436 an unknown preconditioner. See Table~\ref{TAB FINLEY SOLVER OPTIONS 2} for the solvers supported by \finley.
437 \end{methoddesc}
438
439 \begin{methoddesc}[SolverOptions]{getPreconditioner}{}
440 Returns key of the preconditioner to be used.
441 \end{methoddesc}
442
443 \begin{methoddesc}[SolverOptions]{setPackage}{\optional{package=SolverOptions.DEFAULT}}
444 Sets the solver package to be used as a solver.
445 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}.
446 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)
447 and, if available, \member{SolverOptions.MKL} and \member{SolverOptions.UMFPACK}.
448 \end{methoddesc}
449
450 \begin{methoddesc}[SolverOptions]{getPackage}{}
451 Returns the solver package key
452 \end{methoddesc}
453
454
455 \begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}}
456 resets the diagnostics. If \var{all} is \True all diagnostics including accumulative counters are reset.
457 \end{methoddesc}
458
459 \begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}}
460 Returns the diagnostic information \var{name}. The following keywords are
461 supported:
462 \begin{itemize}
463 \item "num_iter": the number of iteration steps
464 \item "cum_num_iter": the cumulative number of iteration steps
465 \item "num_level": the number of level in multi level solver
466 \item "num_inner_iter": the number of inner iteration steps
467 \item"cum_num_inner_iter": the cumulative number of inner iteration steps
468 \item"time": execution time
469 \item "cum_time": cumulative execution time
470 \item "set_up_time": time to set up of the solver, typically this includes factorization and reordering
471 \item "cum_set_up_time": cumulative time to set up of the solver
472 \item "residual_norm": norm of the final residual
473 \item "converged": return self.__converged
474 \end{itemize}
475 \end{methoddesc}
476
477
478 \begin{methoddesc}[SolverOptions]{hasConverged}{}
479 Returns \True if the last solver call has been finalized successfully.
480 If an exception has been thrown by the solver the status of this flag is undefined.
481 \end{methoddesc}
482
483 \begin{methoddesc}[SolverOptions]{setCoarsening}{\optional{method=SolverOptions.DEFAULT}}
484 Sets the key of the coarsening method to be applied in \AMG.
485 The value of \var{method} must be one of the constants
486 \member{SolverOptions.DEFAULT}
487 \member{SolverOptions.YAIR_SHAPIRA_COARSENING},
488 \member{SolverOptions.RUGE_STUEBEN_COARSENING}, or \member{SolverOptions.AGGREGATION_COARSENING}.
489 \end{methoddesc}
490
491 \begin{methoddesc}[SolverOptions]{getCoarsening}{}
492 Returns the key of the coarsening algorithm to be applied \AMG.
493 \end{methoddesc}
494
495 \begin{methoddesc}[SolverOptions]{setReordering}{\optional{ordering=SolverOptions.DEFAULT_REORDERING}}
496 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
497 \member{SolverOptions.NO_REORDERING}, \member{SolverOptions.MINIMUM_FILL_IN},
498 \member{SolverOptions.NESTED_DISSECTION}, or \member{SolverOptions.DEFAULT_REORDERING}.
499 \end{methoddesc}
500
501 \begin{methoddesc}[SolverOptions]{getReordering}{}
502 Returns the key of the reordering method to be applied if supported by the solver.
503 \end{methoddesc}
504
505 \begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}}
506 Sets the number of iterations steps after which \GMRES is performing a restart.
507 If \var{restart} is equal to \var{None} no restart is performed.
508 \end{methoddesc}
509
510
511 \begin{methoddesc}[SolverOptions]{getRestart}{}
512 Returns the number of iterations steps after which \GMRES is performing a restart.
513 \end{methoddesc}
514
515 \begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}}
516 Sets the number of residuals in \GMRES to be stored for orthogonalization. The more residuals are stored the faster \GMRES converged but
517 \end{methoddesc}
518
519 \begin{methoddesc}[SolverOptions]{getTruncation}{}
520 Returns the number of residuals in \GMRES to be stored for orthogonalization
521 \end{methoddesc}
522
523
524 \begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}}
525 Sets the maximum number of iteration steps
526 \end{methoddesc}
527
528 \begin{methoddesc}[SolverOptions]{getIterMax}{}
529 Returns maximum number of iteration steps
530 \end{methoddesc}
531
532 \begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}}
533 Sets the maximum number of coarsening levels to be used in the \AMG solver or preconditioner.
534 \end{methoddesc}
535
536 \begin{methoddesc}[SolverOptions]{getLevelMax}{}
537 Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
538 \end{methoddesc}
539
540 \begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.05}}
541 Sets the threshold for coarsening in the \AMG solver or preconditioner
542 \end{methoddesc}
543
544 \begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{}
545 Returns the threshold for coarsening in the \AMG solver or preconditioner
546 \end{methoddesc}
547
548 \begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}}
549 Sets the minumum size of the coarsest level matrix in AMG.
550 \end{methoddesc}
551
552 \begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{}
553 Returns the minumum size of the coarsest level matrix in AMG.
554 \end{methoddesc}
555
556 \begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}}
557 Sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
558 \end{methoddesc}
559
560 \begin{methoddesc}[SolverOptions]{getNumSweeps}{}
561 Returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
562 \end{methoddesc}
563
564 \begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}}
565 Sets the number of sweeps in the pre-smoothing step of \AMG
566 \end{methoddesc}
567
568 \begin{methoddesc}[SolverOptions]{getNumPreSweeps}{}
569 Returns the number of sweeps in the pre-smoothing step of \AMG
570 \end{methoddesc}
571
572 \begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}}
573 Sets the number of sweeps in the post-smoothing step of \AMG
574 \end{methoddesc}
575
576 \begin{methoddesc}[SolverOptions]{getNumPostSweeps}{}
577 Returns he number of sweeps sweeps in the post-smoothing step of \AMG
578 \end{methoddesc}
579
580 \begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}}
581 Sets the relative tolerance for the solver. The actually meaning of tolerance depends
582 on the underlying PDE library. In most cases, the tolerance
583 will only consider the error from solving the discrete problem but will
584 not consider any discretization error.
585 \end{methoddesc}
586
587 \begin{methoddesc}[SolverOptions]{getTolerance}{}
588 Returns the relative tolerance for the solver
589 \end{methoddesc}
590
591 \begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}}
592 Sets the absolute tolerance for the solver. The actually meaning of tolerance depends
593 on the underlying PDE library. In most cases, the tolerance
594 will only consider the error from solving the discrete problem but will
595 not consider any discretization error.
596 \end{methoddesc}
597
598 \begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{}
599 Returns the absolute tolerance for the solver
600 \end{methoddesc}
601
602
603 \begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}}
604 Sets the relative tolerance for an inner iteration scheme for instance
605 on the coarsest level in a multi-level scheme.
606 \end{methoddesc}
607
608 \begin{methoddesc}[SolverOptions]{getInnerTolerance}{}
609 Returns the relative tolerance for an inner iteration scheme
610 \end{methoddesc}
611
612 \begin{methoddesc}[SolverOptions]{setDropTolerance}{\optional{drop_tol=0.01}}
613 Sets the relative drop tolerance in ILUT
614 \end{methoddesc}
615
616 \begin{methoddesc}[SolverOptions]{getDropTolerance}{}
617 Returns the relative drop tolerance in \ILUT
618 \end{methoddesc}
619
620
621 \begin{methoddesc}[SolverOptions]{setDropStorage}{\optional{storage=2.}}
622 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.
623 \end{methoddesc}
624
625 \begin{methoddesc}[SolverOptions]{getDropStorage}{}
626 Returns the maximum allowed increase in storage for \ILUT
627 \end{methoddesc}
628
629 \begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}}
630 Sets the relaxation factor used to add dropped elements in \RILU to the main diagonal.
631 \end{methoddesc}
632
633 \begin{methoddesc}[SolverOptions]{getRelaxationFactor}{}
634 Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.
635 \end{methoddesc}
636
637 \begin{methoddesc}[SolverOptions]{isSymmetric}{}
638 Returns \True is the descrete system is indicated as symmetric.
639 \end{methoddesc}
640
641 \begin{methoddesc}[SolverOptions]{setSymmetryOn}{}
642 Sets the symmetry flag to indicate that the coefficient matrix is symmetric.
643 \end{methoddesc}
644
645 \begin{methoddesc}[SolverOptions]{setSymmetryOff}{}
646 Clears the symmetry flag for the coefficient matrix.
647 \end{methoddesc}
648
649 \begin{methoddesc}[SolverOptions]{isVerbose}{}
650 Returns \True if the solver is expected to be verbose.
651 \end{methoddesc}
652
653
654 \begin{methoddesc}[SolverOptions]{setVerbosityOn}{}
655 Switches the verbosity of the solver on.
656 \end{methoddesc}
657
658
659 \begin{methoddesc}[SolverOptions]{setVerbosityOff}{}
660 Switches the verbosity of the solver off.
661 \end{methoddesc}
662
663
664 \begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{}
665 Returns \True if the tolerance of the inner solver is selected automatically.
666 Otherwise the inner tolerance set by \member{setInnerTolerance} is used.
667 \end{methoddesc}
668
669 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{}
670 Switches the automatic selection of inner tolerance on
671 \end{methoddesc}
672
673 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{}
674 Switches the automatic selection of inner tolerance off.
675 \end{methoddesc}
676
677 \begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}}
678 Sets the maximum number of iteration steps for the inner iteration.
679 \end{methoddesc}
680
681 \begin{methoddesc}[SolverOptions]{getInnerIterMax}{}
682 Returns maximum number of inner iteration steps.
683 \end{methoddesc}
684
685 \begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{}
686 Returns \True if a failure to meet the stopping criteria within the
687 given number of iteration steps is not raising in exception. This is useful
688 if a solver is used in a non-linear context where the non-linear solver can
689 continue even if the returned the solution does not necessarily meet the
690 stopping criteria. One can use the \member{hasConverged} method to check if the
691 last call to the solver was successful.
692 \end{methoddesc}
693
694 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{}
695 Switches the acceptance of a failure of convergence on.
696 \end{methoddesc}
697
698 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{}
699 Switches the acceptance of a failure of convergence off.
700 \end{methoddesc}
701
702 \begin{memberdesc}[SolverOptions]{DEFAULT}
703 default method, preconditioner or package to be used to solve the PDE. An appropriate method should be
704 chosen by the used PDE solver library.
705 \end{memberdesc}
706
707 \begin{memberdesc}[SolverOptions]{MKL}
708 the \MKL library by Intel,~\Ref{MKL}\footnote{The \MKL library will only be available when the Intel compilation environment is used.}.
709 \end{memberdesc}
710
711 \begin{memberdesc}[SolverOptions]{UMFPACK}
712 the \UMFPACK,~\Ref{UMFPACK}. Remark: \UMFPACK is not parallelized.
713 \end{memberdesc}
714
715 \begin{memberdesc}[SolverOptions]{PASO}
716 \PASO is the solver library of \finley, see \Sec{CHAPTER ON FINLEY}.
717 \end{memberdesc}
718
719 \begin{memberdesc}[SolverOptions]{ITERATIVE}
720 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.
721 \end{memberdesc}
722
723 \begin{memberdesc}[SolverOptions]{DIRECT}
724 the default direct linear solver.
725 \end{memberdesc}
726
727 \begin{memberdesc}[SolverOptions]{CHOLEVSKY}
728 direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE.
729 \end{memberdesc}
730
731 \begin{memberdesc}[SolverOptions]{PCG}
732 preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE.
733 \end{memberdesc}
734
735 \begin{memberdesc}[SolverOptions]{TFQMR}
736 transpose-free quasi-minimal residual method, see~\Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}. \end{memberdesc}
737
738 \begin{memberdesc}[SolverOptions]{GMRES}
739 the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters
740 \var{truncation} and \var{restart} of \method{getSolution}.
741 \end{memberdesc}
742
743 \begin{memberdesc}[SolverOptions]{MINRES}
744 minimal residual method method, \index{linear solver!MINRES}\index{MINRES} \end{memberdesc}
745
746 \begin{memberdesc}[SolverOptions]{LUMPING}
747 uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
748 condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
749 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
750 but is expected to converge to zero when the mesh gets finer.
751 Lumping does not use the linear system solver library.
752 \end{memberdesc}
753
754 \begin{memberdesc}[SolverOptions]{PRES20}
755 the GMRES method with truncation after five residuals and
756 restart after 20 steps, see~\Ref{WEISS}.
757 \end{memberdesc}
758
759 \begin{memberdesc}[SolverOptions]{CGS}
760 conjugate gradient squared method, see~\Ref{WEISS}.
761 \end{memberdesc}
762
763 \begin{memberdesc}[SolverOptions]{BICGSTAB}
764 stabilized bi-conjugate gradients methods, see~\Ref{WEISS}.
765 \end{memberdesc}
766
767 \begin{memberdesc}[SolverOptions]{SSOR}
768 symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support
769 this as a solver.
770 \end{memberdesc}
771
772 \begin{memberdesc}[SolverOptions]{ILU0}
773 the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}.
774 \end{memberdesc}
775
776 \begin{memberdesc}[SolverOptions]{ILUT}
777 the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the LU-factorization element with
778 relative size less then \member{getDropTolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
779 \member{getDropStorage}-fold of the stiffness matrix. \member{getDropTolerance} and \member{getDropStorage} are both set in the
780 \method{getSolution} call.
781 \end{memberdesc}
782
783 \begin{memberdesc}[SolverOptions]{JACOBI}
784 the Jacobi preconditioner, see~\Ref{Saad}.
785 \end{memberdesc}
786
787
788 \begin{memberdesc}[SolverOptions]{AMG}
789 the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used
790 in a preconditioner.
791 \end{memberdesc}
792
793 \begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL}
794 the symmetric Gauss-Seidel preconditioner, see~\Ref{Saad}.
795 \member{getNumSweeps()} is the number of sweeps used.
796 \end{memberdesc}
797
798 \begin{memberdesc}[SolverOptions]{RILU}
799 relaxed incomplete LU factorization preconditioner, see~\Ref{RELAXILU}. This method is similar to \ILU0 but dropped elements are added to the main diagonal
800 with the relaxation factor \member{getRelaxationFactor}
801 \end{memberdesc}
802
803 \begin{memberdesc}[SolverOptions]{REC_ILU}
804 recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILU0 but applies reordering during the factorization.
805 \end{memberdesc}
806
807 \begin{memberdesc}[SolverOptions]{NO_REORDERING}
808 no ordering is used during factorization.
809 \end{memberdesc}
810
811 \begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING}
812 the default reordering method during factorization.
813 \end{memberdesc}
814
815 \begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN}
816 applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or
817 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
818 \end{memberdesc}
819
820 \begin{memberdesc}[SolverOptions]{NESTED_DISSECTION}
821 applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or
822 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
823 \end{memberdesc}
824
825 \begin{memberdesc}[SolverOptions]{TRILINOS}
826 the Trilinos library is used as a solver~\Ref{TRILINOS}
827 \end{memberdesc}
828
829 \begin{memberdesc}[SolverOptions]{SUPER_LU}
830 the SuperLU library is used as a solver~\Ref{SuperLU}
831 \end{memberdesc}
832
833 \begin{memberdesc}[SolverOptions]{PASTIX}
834 the Pastix library is used as a solver~\Ref{PASTIX}
835 \end{memberdesc}
836
837
838 \begin{memberdesc}[SolverOptions]{YAIR_SHAPIRA_COARSENING}
839 \AMG coarsening method by Yair-Shapira
840 \end{memberdesc}
841
842 \begin{memberdesc}[SolverOptions]{RUGE_STUEBEN_COARSENING} \AMG coarsening method by Ruge and Stueben
843 \end{memberdesc}
844
845 \begin{memberdesc}[SolverOptions]{AGGREGATION_COARSENING} \AMG coarsening using (symmetric) aggregation
846 \end{memberdesc}
847
848 \begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER}
849 no preconditioner is applied.
850 \end{memberdesc}
851

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26