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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 625 - (hide 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 jgs 102 % $Id$
2 gross 625 %
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 jgs 102
10 gross 625
11 gross 599 \chapter{The module \linearPDEs}
12 jgs 102
13     \declaremodule{extension}{linearPDEs} \modulesynopsis{Linear partial pifferential equation handler}
14 gross 599 The module \linearPDEs provides an interface to define and solve linear partial
15     differential equations within \escript. \linearPDEs does not provide any
16 jgs 107 solver capabilities in itself but hands the PDE over to
17 jgs 102 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 jgs 107 For a single PDE with a solution with a single component the linear PDE is defined in the
33 jgs 102 following form:
34     \begin{equation}\label{LINEARPDE.SINGLE.1}
35 gross 625 -(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 jgs 102 \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 gross 625 or \eqn{LINEARPDE.SINGLE.2}.
56    
57 jgs 102 For a system of PDEs and a solution with several components the PDE has the form
58     \begin{equation}\label{LINEARPDE.SYSTEM.1}
59 gross 625 -(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 jgs 102 \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 gross 625 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 jgs 102 \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 gross 625 $r$ and $q$ are each \RankOne. Notice that not necessarily all components must
72     have a constraint at all locations.
73    
74 jgs 102 \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 gross 625
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 jgs 102 \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 gross 625 \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 jgs 102 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 gross 625 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
153 jgs 102 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 gross 625 \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
165     returns \True if lumping is switched on. Otherwise \False is returned.
166 jgs 102 \end{methoddesc}
167    
168 gross 625 \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 jgs 102 \end{methoddesc}
172    
173 gross 625 \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 jgs 102
180 gross 625 \begin{methoddesc}[LinearPDE]{getTolerance}{}
181     returns the current tolerance of the solution
182 jgs 102 \end{methoddesc}
183    
184 gross 625 \begin{methoddesc}[LinearPDE]{getDomain}{}
185     returns the \Domain of the PDE.
186 jgs 102 \end{methoddesc}
187    
188 gross 625 \begin{methoddesc}[LinearPDE]{getDim}{}
189     returns the spatial dimension of the PDE.
190 jgs 102 \end{methoddesc}
191    
192 gross 625 \begin{methoddesc}[LinearPDE]{getNumEquations}{}
193     returns the number of equations.
194     \end{methoddesc}
195 jgs 102
196 gross 625 \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
197     returns the number of components of the solution.
198 jgs 102 \end{methoddesc}
199    
200 gross 625 \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 jgs 102 \end{methoddesc}
207    
208 gross 625 \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 jgs 102 \end{methoddesc}
212    
213 gross 625 \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}
214     \begin{methoddesc}[LinearPDE]{getSolverMethod}{}
215     \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=None}}
216     \begin{methoddesc}[LinearPDE]{getSolverPackage}{}
217    
218 jgs 102 \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 gross 625 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 jgs 102 \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 gross 625 \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
247 jgs 102 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 gross 625 \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 jgs 102 \end{methoddesc}
273    
274 gross 625 ==================
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 jgs 102
280 gross 625 \begin{memberdesc}[LinearPDE]{SCSL}
281     \end{memberdesc}
282 jgs 102
283 gross 625 \begin{memberdesc}[LinearPDE]{MKL}
284     \end{memberdesc}
285 jgs 102
286 gross 625 \begin{memberdesc}[LinearPDE]{UMFPACK}
287     \end{memberdesc}
288 jgs 102
289 gross 625 \begin{memberdesc}[LinearPDE]{PASO}
290     \end{memberdesc}
291 jgs 102
292 gross 625 \begin{memberdesc}[LinearPDE]{ITERATIVE}
293 jgs 102
294 gross 625 \end{memberdesc}
295 jgs 102
296 gross 625 \begin{memberdesc}[LinearPDE]{DIRECT}
297     direct linear solver~\Ref{SAAD}
298     \end{memberdesc}
299 jgs 102
300 gross 625 \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 jgs 110
304 gross 625 \begin{memberdesc}[LinearPDE]{PCG}
305     preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.
306     \end{memberdesc}
307 jgs 110
308 gross 625 \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 jgs 102
313 gross 625 \begin{memberdesc}[LinearPDE]{LUMPING}
314     conjugate residual method, see~\Ref{WEISS}.
315     \end{memberdesc}
316 jgs 107
317 gross 625 \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 jgs 107 \end{memberdesc}
326    
327 gross 625 \begin{memberdesc}[LinearPDE]{BICGSTAB}
328     stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.
329 jgs 107 \end{memberdesc}
330    
331 gross 625 \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 jgs 107
340 gross 625
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 jgs 102 \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 gross 625
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