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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2524 - (show annotations)
Wed Jul 8 00:39:26 2009 UTC (11 years ago) by artak
File MIME type: application/x-tex
File size: 37356 byte(s)
Minimum size of the coarsest level matrix option added to solver options
1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (c) 2003-2008 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().setMaxIter(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
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.
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.
447 \end{methoddesc}
448
449 \begin{methoddesc}[SolverOptions]{getPackage}{}
450 Returns the solver package key
451 \end{methoddesc}
452
453
454 \begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}}
455 resets the diagnostics. If \var{all} is \True all diagnostics including accumulative counters are reset.
456 \end{methoddesc}
457
458 \begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}}
459 Returns the diagnostic information \var{name}. The following keywords are
460 supported:
461 \begin{itemize}
462 \item "num_iter": the number of iteration steps
463 \item "cum_num_iter": the cumulative number of iteration steps
464 \item "num_level": the number of level in multi level solver
465 \item "num_inner_iter": the number of inner iteration steps
466 \item"cum_num_inner_iter": the cumulative number of inner iteration steps
467 \item"time": execution time
468 \item "cum_time": cumulative execution time
469 \item "set_up_time": time to set up of the solver, typically this includes factorization and reordering
470 \item "cum_set_up_time": cumulative time to set up of the solver
471 \item "residual_norm": norm of the final residual
472 \item "converged": return self.__converged
473 \end{itemize}
474 \end{methoddesc}
475
476
477 \begin{methoddesc}[SolverOptions]{hasConverged}{}
478 Returns \True if the last solver call has been finalized successfully.
479 If an exception has been thrown by the solver the status of this flag is undefined.
480 \end{methoddesc}
481
482 \begin{methoddesc}[SolverOptions]{setCoarsening}{\optional{method=SolverOptions.DEFAULT}}
483 Sets the key of the coarsening method to be applied in \AMG.
484 The value of \var{method} must be one of the constants
485 \member{SolverOptions.DEFAULT}
486 \member{SolverOptions.YAIR_SHAPIRA_COARSENING},
487 \member{SolverOptions.RUGE_STUEBEN_COARSENING}, or \member{SolverOptions.AGGREGATION_COARSENING}.
488 \end{methoddesc}
489
490 \begin{methoddesc}[SolverOptions]{getCoarsening}{}
491 Returns the key of the coarsening algorithm to be applied \AMG.
492 \end{methoddesc}
493
494 \begin{methoddesc}[SolverOptions]{setReordering}{\optional{ordering=SolverOptions.DEFAULT_REORDERING}}
495 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
496 \member{SolverOptions.NO_REORDERING}, \member{SolverOptions.MINIMUM_FILL_IN},
497 \member{SolverOptions.NESTED_DISSECTION}, or \member{SolverOptions.DEFAULT_REORDERING}.
498 \end{methoddesc}
499
500 \begin{methoddesc}[SolverOptions]{getReordering}{}
501 Returns the key of the reordering method to be applied if supported by the solver.
502 \end{methoddesc}
503
504 \begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}}
505 Sets the number of iterations steps after which \GMRES is performing a restart.
506 If \var{restart} is equal to \var{None} no restart is performed.
507 \end{methoddesc}
508
509
510 \begin{methoddesc}[SolverOptions]{getRestart}{}
511 Returns the number of iterations steps after which \GMRES is performing a restart.
512 \end{methoddesc}
513
514 \begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}}
515 Sets the number of residuals in \GMRES to be stored for orthogonalization. The more residuals are stored the faster \GMRES converged but
516 \end{methoddesc}
517
518 \begin{methoddesc}[SolverOptions]{getTruncation}{}
519 Returns the number of residuals in \GMRES to be stored for orthogonalization
520 \end{methoddesc}
521
522
523 \begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}}
524 Sets the maximum number of iteration steps
525 \end{methoddesc}
526
527 \begin{methoddesc}[SolverOptions]{getIterMax}{}
528 Returns maximum number of iteration steps
529 \end{methoddesc}
530
531 \begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}}
532 Sets the maximum number of coarsening levels to be used in the \AMG solver or preconditioner.
533 \end{methoddesc}
534
535 \begin{methoddesc}[SolverOptions]{getLevelMax}{}
536 Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
537 \end{methoddesc}
538
539 \begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.05}}
540 Sets the threshold for coarsening in the \AMG solver or preconditioner
541 \end{methoddesc}
542
543 \begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{}
544 Returns the threshold for coarsening in the \AMG solver or preconditioner
545 \end{methoddesc}
546
547 \begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}}
548 Sets the minumum size of the coarsest level matrix in AMG.
549 \end{methoddesc}
550
551 \begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{}
552 Returns the minumum size of the coarsest level matrix in AMG.
553 \end{methoddesc}
554
555 \begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}}
556 Sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
557 \end{methoddesc}
558
559 \begin{methoddesc}[SolverOptions]{getNumSweeps}{}
560 Returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
561 \end{methoddesc}
562
563 \begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}}
564 Sets the number of sweeps in the pre-smoothing step of \AMG
565 \end{methoddesc}
566
567 \begin{methoddesc}[SolverOptions]{getNumPreSweeps}{}
568 Returns the number of sweeps in the pre-smoothing step of \AMG
569 \end{methoddesc}
570
571 \begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}}
572 Sets the number of sweeps in the post-smoothing step of \AMG
573 \end{methoddesc}
574
575 \begin{methoddesc}[SolverOptions]{getNumPostSweeps}{}
576 Returns he number of sweeps sweeps in the post-smoothing step of \AMG
577 \end{methoddesc}
578
579 \begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}}
580 Sets the relative tolerance for the solver. The actually meaning of tolerance depends
581 on the underlying PDE library. In most cases, the tolerance
582 will only consider the error from solving the discrete problem but will
583 not consider any discretization error.
584 \end{methoddesc}
585
586 \begin{methoddesc}[SolverOptions]{getTolerance}{}
587 Returns the relative tolerance for the solver
588 \end{methoddesc}
589
590 \begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}}
591 Sets the absolute tolerance for the solver. The actually meaning of tolerance depends
592 on the underlying PDE library. In most cases, the tolerance
593 will only consider the error from solving the discrete problem but will
594 not consider any discretization error.
595 \end{methoddesc}
596
597 \begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{}
598 Returns the absolute tolerance for the solver
599 \end{methoddesc}
600
601
602 \begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}}
603 Sets the relative tolerance for an inner iteration scheme for instance
604 on the coarsest level in a multi-level scheme.
605 \end{methoddesc}
606
607 \begin{methoddesc}[SolverOptions]{getInnerTolerance}{}
608 Returns the relative tolerance for an inner iteration scheme
609 \end{methoddesc}
610
611 \begin{methoddesc}[SolverOptions]{setDropTolerance}{\optional{drop_tol=0.01}}
612 Sets the relative drop tolerance in ILUT
613 \end{methoddesc}
614
615 \begin{methoddesc}[SolverOptions]{getDropTolerance}{}
616 Returns the relative drop tolerance in \ILUT
617 \end{methoddesc}
618
619
620 \begin{methoddesc}[SolverOptions]{setDropStorage}{\optional{storage=2.}}
621 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.
622 \end{methoddesc}
623
624 \begin{methoddesc}[SolverOptions]{getDropStorage}{}
625 Returns the maximum allowed increase in storage for \ILUT
626 \end{methoddesc}
627
628 \begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}}
629 Sets the relaxation factor used to add dropped elements in \RILU to the main diagonal.
630 \end{methoddesc}
631
632 \begin{methoddesc}[SolverOptions]{getRelaxationFactor}{}
633 Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.
634 \end{methoddesc}
635
636 \begin{methoddesc}[SolverOptions]{isSymmetric}{}
637 Returns \True is the descrete system is indicated as symmetric.
638 \end{methoddesc}
639
640 \begin{methoddesc}[SolverOptions]{setSymmetryOn}{}
641 Sets the symmetry flag to indicate that the coefficient matrix is symmetric.
642 \end{methoddesc}
643
644 \begin{methoddesc}[SolverOptions]{setSymmetryOff}{}
645 Clears the symmetry flag for the coefficient matrix.
646 \end{methoddesc}
647
648 \begin{methoddesc}[SolverOptions]{isVerbose}{}
649 Returns \True if the solver is expected to be verbose.
650 \end{methoddesc}
651
652
653 \begin{methoddesc}[SolverOptions]{setVerbosityOn}{}
654 Switches the verbosity of the solver on.
655 \end{methoddesc}
656
657
658 \begin{methoddesc}[SolverOptions]{setVerbosityOff}{}
659 Switches the verbosity of the solver off.
660 \end{methoddesc}
661
662
663 \begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{}
664 Returns \True if the tolerance of the inner solver is selected automatically.
665 Otherwise the inner tolerance set by \member{setInnerTolerance} is used.
666 \end{methoddesc}
667
668 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{}
669 Switches the automatic selection of inner tolerance on
670 \end{methoddesc}
671
672 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{}
673 Switches the automatic selection of inner tolerance off.
674 \end{methoddesc}
675
676 \begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}}
677 Sets the maximum number of iteration steps for the inner iteration.
678 \end{methoddesc}
679
680 \begin{methoddesc}[SolverOptions]{getInnerIterMax}{}
681 Returns maximum number of inner iteration steps.
682 \end{methoddesc}
683
684 \begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{}
685 Returns \True if a failure to meet the stopping criteria within the
686 given number of iteration steps is not raising in exception. This is useful
687 if a solver is used in a non-linear context where the non-linear solver can
688 continue even if the returned the solution does not necessarily meet the
689 stopping criteria. One can use the \member{hasConverged} method to check if the
690 last call to the solver was successful.
691 \end{methoddesc}
692
693 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{}
694 Switches the acceptance of a failure of convergence on.
695 \end{methoddesc}
696
697 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{}
698 Switches the acceptance of a failure of convergence off.
699 \end{methoddesc}
700
701 \begin{memberdesc}[SolverOptions]{DEFAULT}
702 default method, preconditioner or package to be used to solve the PDE. An appropriate method should be
703 chosen by the used PDE solver library.
704 \end{memberdesc}
705
706 \begin{memberdesc}[SolverOptions]{MKL}
707 the MKL library by Intel,~\Ref{MKL}\footnote{The MKL library will only be available when the Intel compilation environment is used.}.
708 \end{memberdesc}
709
710 \begin{memberdesc}[SolverOptions]{UMFPACK}
711 the UMFPACK,~\Ref{UMFPACK}. Remark: UMFPACK is not parallelized.
712 \end{memberdesc}
713
714 \begin{memberdesc}[SolverOptions]{PASO}
715 the solver library of \finley, see \Sec{CHAPTER ON FINLEY}.
716 \end{memberdesc}
717
718 \begin{memberdesc}[SolverOptions]{ITERATIVE}
719 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.
720 \end{memberdesc}
721
722 \begin{memberdesc}[SolverOptions]{DIRECT}
723 the default direct linear solver.
724 \end{memberdesc}
725
726 \begin{memberdesc}[SolverOptions]{CHOLEVSKY}
727 direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE.
728 \end{memberdesc}
729
730 \begin{memberdesc}[SolverOptions]{PCG}
731 preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE.
732 \end{memberdesc}
733
734 \begin{memberdesc}[SolverOptions]{TFQMR}
735 transpose-free quasi-minimal residual method, see~\Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}. \end{memberdesc}
736
737 \begin{memberdesc}[SolverOptions]{GMRES}
738 the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters
739 \var{truncation} and \var{restart} of \method{getSolution}.
740 \end{memberdesc}
741
742 \begin{memberdesc}[SolverOptions]{MINRES}
743 minimal residual method method, \index{linear solver!MINRES}\index{MINRES} \end{memberdesc}
744
745 \begin{memberdesc}[SolverOptions]{LUMPING}
746 uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
747 condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
748 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
749 but is expected to converge to zero when the mesh gets finer.
750 Lumping does not use the linear system solver library.
751 \end{memberdesc}
752
753 \begin{memberdesc}[SolverOptions]{PRES20}
754 the GMRES method with truncation after five residuals and
755 restart after 20 steps, see~\Ref{WEISS}.
756 \end{memberdesc}
757
758 \begin{memberdesc}[SolverOptions]{CGS}
759 conjugate gradient squared method, see~\Ref{WEISS}.
760 \end{memberdesc}
761
762 \begin{memberdesc}[SolverOptions]{BICGSTAB}
763 stabilized bi-conjugate gradients methods, see~\Ref{WEISS}.
764 \end{memberdesc}
765
766 \begin{memberdesc}[SolverOptions]{SSOR}
767 symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support
768 this as a solver.
769 \end{memberdesc}
770
771 \begin{memberdesc}[SolverOptions]{ILU0}
772 the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}.
773 \end{memberdesc}
774
775 \begin{memberdesc}[SolverOptions]{ILUT}
776 the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the LU-factorization element with
777 relative size less then \member{getDropTolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
778 \member{getDropStorage}-fold of the stiffness matrix. \member{getDropTolerance} and \member{getDropStorage} are both set in the
779 \method{getSolution} call.
780 \end{memberdesc}
781
782 \begin{memberdesc}[SolverOptions]{JACOBI}
783 the Jacobi preconditioner, see~\Ref{Saad}.
784 \end{memberdesc}
785
786
787 \begin{memberdesc}[SolverOptions]{AMG}
788 the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used
789 in a preconditioner.
790 \end{memberdesc}
791
792 \begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL}
793 the symmetric Gauss-Seidel preconditioner, see~\Ref{Saad}.
794 \member{getNumSweeps()} is the number of sweeps used.
795 \end{memberdesc}
796
797 \begin{memberdesc}[SolverOptions]{RILU}
798 relaxed incomplete LU factorization preconditioner, see~\Ref{RELAXILU}. This method is similar to \ILU0 but dropped elements are added to the main diagonal
799 with the relaxation factor \member{getRelaxationFactor}
800 \end{memberdesc}
801
802 \begin{memberdesc}[SolverOptions]{REC_ILU}
803 recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILU0 but applies reordering during the factorization.
804 \end{memberdesc}
805
806 \begin{memberdesc}[SolverOptions]{NO_REORDERING}
807 no ordering is used during factorization.
808 \end{memberdesc}
809
810 \begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING}
811 the default reordering method during factorization.
812 \end{memberdesc}
813
814 \begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN}
815 applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or
816 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
817 \end{memberdesc}
818
819 \begin{memberdesc}[SolverOptions]{NESTED_DISSECTION}
820 applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or
821 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
822 \end{memberdesc}
823
824 \begin{memberdesc}[SolverOptions]{TRILINOS}
825 the Trilinos library is used as a solver~\Ref{TRILINOS}
826 \end{memberdesc}
827
828 \begin{memberdesc}[SolverOptions]{SUPER_LU}
829 the SuperLU library is used as a solver~\Ref{SuperLU}
830 \end{memberdesc}
831
832 \begin{memberdesc}[SolverOptions]{PASTIX}
833 the Pastix library is used as a solver~\Ref{PASTIX}
834 \end{memberdesc}
835
836
837 \begin{memberdesc}[SolverOptions]{YAIR_SHAPIRA_COARSENING}
838 \AMG coarsening method by Yair-Shapira
839 \end{memberdesc}
840
841 \begin{memberdesc}[SolverOptions]{RUGE_STUEBEN_COARSENING} \AMG coarsening method by Ruge and Stueben
842 \end{memberdesc}
843
844 \begin{memberdesc}[SolverOptions]{AGGREGATION_COARSENING} \AMG coarsening using (symmetric) aggregation
845 \end{memberdesc}
846
847 \begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER}
848 no preconditioner is applied.
849 \end{memberdesc}
850

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26