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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 625 - (show annotations)
Thu Mar 23 00:41:25 2006 UTC (14 years ago) by gross
File MIME type: application/x-tex
File size: 15950 byte(s)
some updates and linearPDE.tex switched off
1 % $Id$
2 %
3 % Copyright © 2006 by ACcESS MNRF
4 % \url{http://www.access.edu.au
5 % Primary Business: Queensland, Australia.
6 % Licensed under the Open Software License version 3.0
7 % http://www.opensource.org/licenses/osl-3.0.php
8 %
9
10
11 \chapter{The module \linearPDEs}
12
13 \declaremodule{extension}{linearPDEs} \modulesynopsis{Linear partial pifferential equation handler}
14 The module \linearPDEs provides an interface to define and solve linear partial
15 differential equations within \escript. \linearPDEs does not provide any
16 solver capabilities in itself but hands the PDE over to
17 the PDE solver library defined through the \Domain of the PDE.
18 The general interface is provided through the \LinearPDE class. The
19 \AdvectivePDE which is derived from the \LinearPDE class
20 provides an interface to PDE dominated by its advective terms. The \Poisson
21 class which is also derived form the \LinearPDE class should be used
22 to define the Poisson equation \index{Poisson}.
23
24 \section{\LinearPDE Class}
25 \label{SEC LinearPDE}
26
27 The \LinearPDE class is used to define a general linear, steady, second order PDE
28 for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.
29 In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes
30 the outer normal field on $\Gamma$.
31
32 For a single PDE with a solution with a single component the linear PDE is defined in the
33 following form:
34 \begin{equation}\label{LINEARPDE.SINGLE.1}
35 -(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 \; .
36 \end{equation}
37 $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.
38 The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through \Data objects in the
39 \Function on the PDE or objects that can be converted into such \Data objects.
40 $A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar.
41 The following natural
42 boundary conditions are considered \index{boundary condition!natural} on $\Gamma$:
43 \begin{equation}\label{LINEARPDE.SINGLE.2}
44 n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y \;.
45 \end{equation}
46 Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are
47 each a \Scalar in the \FunctionOnBoundary. Constraints \index{constraint} for the solution prescribing the value of the
48 solution at certain locations in the domain. They have the form
49 \begin{equation}\label{LINEARPDE.SINGLE.3}
50 u=r \mbox{ where } q>0
51 \end{equation}
52 $r$ and $q$ are each \Scalar where $q$ is the characteristic function
53 \index{characteristic function} defining where the constraint is applied.
54 The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other condition set by \eqn{LINEARPDE.SINGLE.1}
55 or \eqn{LINEARPDE.SINGLE.2}.
56
57 For a system of PDEs and a solution with several components the PDE has the form
58 \begin{equation}\label{LINEARPDE.SYSTEM.1}
59 -(A\hackscore{ijkl} u\hackscore{k,l}){,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} \; .
60 \end{equation}
61 $A$ is a \RankFour, $B$ and $C$ are each a \RankThree, $D$ and $X$ are each a \RankTwo and $Y$ is a \RankOne.
62 The natural boundary conditions \index{boundary condition!natural} take the form:
63 \begin{equation}\label{LINEARPDE.SYSTEM.2}
64 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} \;.
65 \end{equation}
66 The coefficient $d$ is a \RankTwo and $y$ is a
67 \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form
68 \begin{equation}\label{LINEARPDE.SYSTEM.3}
69 u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
70 \end{equation}
71 $r$ and $q$ are each \RankOne. Notice that not necessarily all components must
72 have a constraint at all locations.
73
74 \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$
75 in the domain $\Omega$. To specify the conditions across the discontinuity we are using the
76 generalised flux $J$ which is in the case of a systems of PDEs and several components of the solution
77 defined as
78 \begin{equation}\label{LINEARPDE.SYSTEM.5}
79 J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij}
80 \end{equation}
81 For the case of single solution component and single PDE $J$ is defined
82 \begin{equation}\label{LINEARPDE.SINGLE.5}
83 J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j}
84 \end{equation}
85 In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the
86 discontinuity pointing from side 0 towards side 1. For a system of PDEs
87 the contact condition takes the form
88 \begin{equation}\label{LINEARPDE.SYSTEM.6}
89 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} \; .
90 \end{equation}
91 where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the
92 discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference
93 of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.
94 The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a
95 \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.
96 In case of a single PDE and a single component solution the contact condition takes the form
97 \begin{equation}\label{LINEARPDE.SINGLE.6}
98 n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u]
99 \end{equation}
100 In this case the the coefficient $d^{contact}$ and $y^{contact}$ are eaach \Scalar
101 both in the \FunctionOnContactZero or \FunctionOnContactOne.
102
103 The PDE is symmetrical \index{symmetrical} if
104 \begin{equation}\label{LINEARPDE.SINGLE.4}
105 A\hackscore{jl}=A\hackscore{lj} \mbox{ and } B\hackscore{j}=C\hackscore{j}
106 \end{equation}
107 The system of PDEs is symmetrical \index{symmetrical} if
108 \begin{eqnarray}
109 \label{LINEARPDE.SYSTEM.4}
110 A\hackscore{ijkl}=A\hackscore{klij} \\
111 B\hackscore{ijk}=C\hackscore{kij} \\
112 D\hackscore{ik}=D\hackscore{ki} \\
113 d\hackscore{ik}=d\hackscore{ki} \\
114 d^{contact}\hackscore{ik}=d^{contact}\hackscore{ki}
115 \end{eqnarray}
116 Note that different from the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$
117 have to be inspected.
118
119 \section{\LinearPDE class}
120 This is the general class to define a linear PDE in \escript. We list a selction of the most
121 important methods of the class only and refer to reference guide \ReferenceGuide for a complete list.
122
123 \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
124 opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}
125 and \var{numSolutions} gives the number of equations and the number of solutiopn components.
126 If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations
127 and the number solutions, respctively, stay undefined until a coefficient is
128 defined.
129 \end{classdesc}
130
131 \begin{methoddesc}[LinearPDE]{setValue}{
132 \optional{A=Data()}\optional{, B=Data()},
133 \optional{, C=Data()}\optional{, D=Data()}
134 \optional{, X=Data()}\optional{, Y=Data()}
135 \optional{, d=Data()}\optional{, y=Data()}
136 \optional{, d_contact=Data()}\optional{, y_contact=Data()}
137 \optional{, q=Data()}\optional{, r=Data()}}
138 assigns new values to coefficients.
139 If the new coefficient value is not a \Data object, it is converted into a \Data object in the
140 appropriate \FunctionSpace.
141 \end{methoddesc}
142
143 \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
144 return the value assigned to coefficient \var{name}. If \var{name} is not a valid name
145 an exception is raised.
146 \end{methoddesc}
147
148 \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
149 returns the shape of coefficient \var{name} even if no value has been assigned to it.
150 \end{methoddesc}
151
152 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
153 returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.
154 \end{methoddesc}
155
156 \begin{methoddesc}[LinearPDE]{setDebugOn}{}
157 switches the debug mode to on.
158 \end{methoddesc}
159
160 \begin{methoddesc}[LinearPDE]{setDebugOff}{}
161 switches the debug mode to on.
162 \end{methoddesc}
163
164 \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
165 returns \True if lumping is switched on. Otherwise \False is returned.
166 \end{methoddesc}
167
168 \begin{methoddesc}[LinearPDE]{setSolverMethod}{\optional{solver=LinearPDE.DEFAULT}\options{, preconditioner=LinearPDE.DEFAULT})
169 sets the solver method and preconditioner to be used. It is pointed out that a PDE solver library
170 may not know the specified solver method but may choose a similar method and preconditioner.
171 \end{methoddesc}
172
173 \begin{methoddesc}[LinearPDE]{setTolerance}{\optional{tol=1.e-8}}:
174 resets the tolerance for solution. The actually meaning of tolerance is
175 depending on the underlying PDE library. In most cases, the tolerance
176 will only consider the error from solving the discerete problem but will
177 not consider any discretization error.
178 \end{methoddesc}
179
180 \begin{methoddesc}[LinearPDE]{getTolerance}{}
181 returns the current tolerance of the solution
182 \end{methoddesc}
183
184 \begin{methoddesc}[LinearPDE]{getDomain}{}
185 returns the \Domain of the PDE.
186 \end{methoddesc}
187
188 \begin{methoddesc}[LinearPDE]{getDim}{}
189 returns the spatial dimension of the PDE.
190 \end{methoddesc}
191
192 \begin{methoddesc}[LinearPDE]{getNumEquations}{}
193 returns the number of equations.
194 \end{methoddesc}
195
196 \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
197 returns the number of components of the solution.
198 \end{methoddesc}
199
200 \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
201 returns \True if the PDE is symmetric and \False otherwise.
202 The method is very computational expensive and should only be
203 called for testing purposes. The symmetry flag is not altered.
204 If \var{verbose}=\True information about where symmetry is violated
205 are printed.
206 \end{methoddesc}
207
208 \begin{methoddesc}[LinearPDE]{getFlux}{u}
209 returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}
210 defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
211 \end{methoddesc}
212
213 \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}
214 \begin{methoddesc}[LinearPDE]{getSolverMethod}{}
215 \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=None}}
216 \begin{methoddesc}[LinearPDE]{getSolverPackage}{}
217
218 \begin{methoddesc}[LinearPDE]{isSymmetric}{}
219 returns \True if the PDE has been indicated to be symmetric.
220 Otherwise \False is returned.
221 \end{methoddesc}
222
223 \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
224 indicates that the PDE is symmetric.
225 \end{methoddesc}
226
227 \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
228 indicates that the PDE is not symmetric.
229 \end{methoddesc}
230
231 \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
232 switches on the reduction of polynomial order for the solution and equation evaluation even if
233 a quadratic or higher interpolation order is defined in the \Domain. This feature may not
234 be supported by all PDE libraries.
235 \end{methoddesc}
236
237 \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
238 switches off the reduction of polynomial order for the solution and
239 equation evaluation.
240 \end{methoddesc}
241
242 \begin{methoddesc}[LinearPDE]{getOperator}{}
243 returns the \Operator of the PDE.
244 \end{methoddesc}
245
246 \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
247 returns the right hand side of the PDE as a \Data object. If
248 \var{ignoreConstraint}=\True the constraints are not considered
249 when building up the right hand side.
250 \end{methoddesc}
251
252 \begin{methoddesc}[LinearPDE]{getSystem}{}
253 returns the \Operator and right hand side of the PDE.
254 \end{methoddesc}
255
256 \begin{methoddesc}[LinearPDE]{getSolution}{
257 \optional{verbose=False}
258 \optional{, reordering=LinearPDE.NO_REORDERING}
259 \optional{, iter_max=1000}
260 \optional{, drop_tolerance=0.01}
261 \optional{, drop_storage=1.20}
262 \optional{, truncation=-1}
263 \optional{, restart=-1}
264 }
265 returns (an approximation of) the solution of the PDE. If \code{verbose=True} some information during the solution process pronted. \var{reordering} selects a reordering methods that is applied before or during the solution process.
266 \var{iter_max} specifies the maximum number of iteration steps that are allowed to reach the specified tolerence.
267 \var{drop_tolerance} specifies a relative tolerance for small elements to be dropped when building a preconditioner
268 (eg. in ILUT \Ref{SAAD}). \var{drop_storage} limits the extra storage allowed when building a preconditioner
269 (eg. in ILUT \Ref{SAAD}). The extra storage is given relative to the size of the siffness matrix, eg.
270 \var{drop_storage=1.2} will allow the preconditioner to use the $1.2$ fold storage space than used
271 for the stiffness matrix. \var{truncation} defines the truncation
272 \end{methoddesc}
273
274 ==================
275 \begin{memberdesc}[LinearPDE]{DEFAULT}
276 default method, preconditioner or package to be used to solve the PDE. An appropriate method should be
277 chosen by the used PDE solver library.
278 \end{memberdesc}
279
280 \begin{memberdesc}[LinearPDE]{SCSL}
281 \end{memberdesc}
282
283 \begin{memberdesc}[LinearPDE]{MKL}
284 \end{memberdesc}
285
286 \begin{memberdesc}[LinearPDE]{UMFPACK}
287 \end{memberdesc}
288
289 \begin{memberdesc}[LinearPDE]{PASO}
290 \end{memberdesc}
291
292 \begin{memberdesc}[LinearPDE]{ITERATIVE}
293
294 \end{memberdesc}
295
296 \begin{memberdesc}[LinearPDE]{DIRECT}
297 direct linear solver~\Ref{SAAD}
298 \end{memberdesc}
299
300 \begin{memberdesc}[LinearPDE]{CHOLEVSKY}
301 direct solver based on Cholevsky factorization (or similar), see~\Ref{SAAD}. The solver will require a symmetric PDE.
302 \end{memberdesc}
303
304 \begin{memberdesc}[LinearPDE]{PCG}
305 preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.
306 \end{memberdesc}
307
308 \begin{memberdesc}[LinearPDE]{GMRES}
309 the GMRES method, see~\Ref{WEISS}. Truncation and restart ar econtrolled by the parameters
310 \var{truncation} and \var{restart} of \method{getSolution}.
311 \end{memberdesc}
312
313 \begin{memberdesc}[LinearPDE]{LUMPING}
314 conjugate residual method, see~\Ref{WEISS}.
315 \end{memberdesc}
316
317 \begin{memberdesc}[LinearPDE]{PRES20}
318 the GMRES method with trunction after five residuals and
319 restart after 20 steps, see~\Ref{WEISS}.
320
321 \begin{memberdesc}[LinearPDE]{CR}
322
323 \begin{memberdesc}[LinearPDE]{CGS}
324 conjugate gradient squared method, see~\Ref{WEISS}.
325 \end{memberdesc}
326
327 \begin{memberdesc}[LinearPDE]{BICGSTAB}
328 stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.
329 \end{memberdesc}
330
331 \begin{memberdesc}[LinearPDE]{SSOR}
332 symmetric successive overrelaxtion method, see~\Ref{WEISS}.
333 \end{memberdesc}
334 \begin{memberdesc}[LinearPDE]{ILU0}
335 \begin{memberdesc}[LinearPDE]{ILUT}
336 \begin{memberdesc}[LinearPDE]{JACOBI}
337 \begin{memberdesc}[LinearPDE]{AMG}
338 \begin{memberdesc}[LinearPDE]{RILU}
339
340
341
342
343 \begin{memberdesc}[LinearPDE]{NO_REORDERING}
344 \begin{memberdesc}[LinearPDE]{MINIMUM_FILL_IN}
345 \begin{memberdesc}[LinearPDE]{NESTED_DISSECTION}
346
347
348
349
350 \begin{memberdesc}[LinearPDE]{BICGSTAB}
351
352
353 \section{The \Poisson Class}
354 The \Poisson class provides an easy way to define and solve the Poisson
355 equation
356 \begin{equation}\label{POISSON.1}
357 -u\hackscore{,ii}=f\; .
358 \end{equation}
359 with homogeneous boundary conditions
360 \begin{equation}\label{POISSON.2}
361 n\hackscore{i}u\hackscore{,i}=0
362 \end{equation}
363 and homogeneous constraints
364 \begin{equation}\label{POISSON.3}
365 u=0 \mbox{ where } q>0
366 \end{equation}
367 $f$ has to be a \Scalar in the \Function and $q$ must be
368 a \Scalar in the \SolutionFS.
369
370 \begin{classdesc}{Poisson}{domain}
371 opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
372 \end{classdesc}
373 \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
374 assigns new values to \var{f} and \var{q}.
375 \end{methoddesc}
376
377 \section{The \Helmholtz Class}
378
379 \section{The \Lame Class}
380

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26