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 |
|