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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 104 - (hide annotations)
Fri Dec 17 07:43:12 2004 UTC (15 years, 7 months ago) by jgs
File MIME type: application/x-tex
File size: 16217 byte(s)
*** empty log message ***

1 jgs 102 % $Id$
2    
3     \chapter{The module \linearPDEsPack}
4    
5     \declaremodule{extension}{linearPDEs} \modulesynopsis{Linear partial pifferential equation handler}
6     The module \linearPDEsPack provides an interface to define and solve linear partial
7     differential equations within \escript. \linearPDEsPack does not provide any
8     solver capabilities in itself but hand the PDE over to
9     the PDE solver library defined through the \Domain of the PDE.
10     The general interface is provided through the \LinearPDE class. The
11     \AdvectivePDE which is derived from the \LinearPDE class
12     provides an interface to PDE dominated by its advective terms. The \Poisson
13     class which is also derived form the \LinearPDE class should be used
14     to define the Poisson equation \index{Poisson}.
15    
16     \section{\LinearPDE Class}
17     \label{SEC LinearPDE}
18    
19     The \LinearPDE class is used to define a general linear, steady, second order PDE
20     for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.
21     In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes
22     the outer normal field on $\Gamma$.
23    
24     A single PDE with a solution with a single component the linear PDE is defined in the
25     following form:
26     \begin{equation}\label{LINEARPDE.SINGLE.1}
27     -(A\hackscore{jl} u\hackscore{,l}){,j}+(B\hackscore{j} u)\hackscore{,j}+C\hackscore{l} u\hackscore{,l}+D u =-X\hackscore{j,j}+Y \; .
28     \end{equation}
29     $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.
30     The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through \Data objects in the
31     \Function on the PDE or objects that can be converted into such \Data objects.
32     $A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar.
33     The following natural
34     boundary conditions are considered \index{boundary condition!natural} on $\Gamma$:
35     \begin{equation}\label{LINEARPDE.SINGLE.2}
36     n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y \;.
37     \end{equation}
38     Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are
39     each a \Scalar in the \FunctionOnBoundary. Constraints \index{constraint} for the solution prescribing the value of the
40     solution at certain locations in the domain. They have the form
41     \begin{equation}\label{LINEARPDE.SINGLE.3}
42     u=r \mbox{ where } q>0
43     \end{equation}
44     $r$ and $q$ are each \Scalar where $q$ is the characteristic function
45     \index{characteristic function} defining where the constraint is applied.
46     The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other condition set by \eqn{LINEARPDE.SINGLE.1}
47     or \eqn{LINEARPDE.SINGLE.2}. The PDE is symmetrical \index{symmetrical} if
48     \begin{equation}\label{LINEARPDE.SINGLE.4}
49     A\hackscore{jl}=A\hackscore{lj} \mbox{ and } B\hackscore{j}=C\hackscore{j}
50     \end{equation}
51     For a system of PDEs and a solution with several components the PDE has the form
52     \begin{equation}\label{LINEARPDE.SYSTEM.1}
53     -(A\hackscore{ijkl} u\hackscore{k,l}){,j}+(B\hackscore{ijk} u_k)\hackscore{,j}+C\hackscore{ikl} u\hackscore{k,l}+D\hackscore{ik} u_k =-X\hackscore{ij,j}+Y\hackscore{i} \; .
54     \end{equation}
55     $A$ is a \RankFour, $B$ and $C$ are each a \RankThree, $D$ and $X$ are each a \RankTwo and $Y$ is a \RankOne.
56     The natural boundary conditions \index{boundary condition!natural} take the form:
57     \begin{equation}\label{LINEARPDE.SYSTEM.2}
58     n\hackscore{j}(A\hackscore{ijkl} u\hackscore{k,l}){,j}+(B\hackscore{ijk} u_k)+d\hackscore{ik} u_k=n\hackscore{j}-X\hackscore{ij}+y\hackscore{i} \;.
59     \end{equation}
60     The coefficient $d$ is a \RankTwo and $y$ is a
61     \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form
62     \begin{equation}\label{LINEARPDE.SYSTEM.3}
63     u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
64     \end{equation}
65     $r$ and $q$ are each \RankOne. Notice that at some locations not necessarily all components must
66     have a constraint. The system of PDEs is symmetrical \index{symmetrical} if
67     \begin{eqnarray}\label{LINEARPDE.SYSTEM.4}
68     A\hackscore{ijkl}=A\hackscore{klij} \\
69     B\hackscore{ijk}=C\hackscore{kij} \\
70     D\hackscore{ik}=D\hackscore{ki} \\
71     d\hackscore{ik}=d\hackscore{ki} \
72     \end{eqnarray}
73     \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$
74     in the domain $\Omega$. To specify the conditions across the discontinuity we are using the
75     generalised flux $J$ which is in the case of a systems of PDEs and several components of the solution
76     defined as
77     \begin{equation}\label{LINEARPDE.SYSTEM.5}
78     J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij}
79     \end{equation}
80     For the case of single solution component and single PDE $J$ is defined
81     \begin{equation}\label{LINEARPDE.SINGLE.5}
82     J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j}
83     \end{equation}
84     In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the
85     discontinuity pointing from side 0 towards side 1. For a system of PDEs
86     the contact condition takes the form
87     \begin{equation}\label{LINEARPDE.SYSTEM.6}
88     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} \; .
89     \end{equation}
90     where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the
91     discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference
92     of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.
93     The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a
94     \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.
95     In case of a single PDE and a single component solution the contact condition takes the form
96     \begin{equation}\label{LINEARPDE.SINGLE.6}
97     n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u]
98     \end{equation}
99     In this case the the coefficient $d^{contact}$ and $y^{contact}$ are eaach \Scalar
100     both in the \FunctionOnContactZero or \FunctionOnContactOne.
101    
102     \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
103     opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}
104     and \var{numSolutions} gives the number of equations and the number of solutiopn components.
105     If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations
106     and the number solutions, respctively, stay undefined until a coefficient is
107     defined.
108     \end{classdesc}
109    
110     \begin{methoddesc}[LinearPDE]{setValues}{arg1,arg2,...,argN}
111     assigns new values to coefficients \var{arg1}, \var{arg2}, $\ldots$ \var{argN}.
112     The coefficients must be one of the valid coefficient names
113     \var{A},
114     \var{B},
115     \var{C},
116     \var{D},
117     \var{X},
118     \var{Y},
119     \var{d},
120     \var{y},
121     \var{dcontact},
122     \var{ycontact},
123     \var{r},
124     or \var{q}.
125     If the coefficient is not a \Data object, it is converted into a \Data object in the
126     appropriate \FunctionSpace.
127     \end{methoddesc}
128    
129     \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
130     return the value assigned to coefficient \var{name}. If \var{name} is not a valid name
131     an exception is raised.
132     \end{methoddesc}
133    
134     \begin{methoddesc}[LinearPDE]{cleanCoefficients}{}
135     resets all coefficients to their initialization values. This method is useful to call when trying to save memory
136     as is releaces eqnerences to coefficients but keeping the differential operator.
137     \end{methoddesc}
138    
139     \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
140     returns the shape of coefficient \var{name} even if no value has been assigned to it.
141     \end{methoddesc}
142    
143    
144     \begin{methoddesc}[LinearPDE]{getFunctionSpaceOfCoefficient}{name}
145     returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.
146     \end{methoddesc}
147    
148     \begin{methoddesc}[LinearPDE]{hasCoefficient}{name}
149     returns \True if \var{name} is valid name of a coefficient
150     \end{methoddesc}
151    
152    
153     \begin{methoddesc}[LinearPDE]{getFunctionSpaceForEquation}{}
154     returns \FunctionSpace of the right hand side which is identical to \FunctionSpace of
155     the result of the PDE operator.
156     \end{methoddesc}
157    
158     \begin{methoddesc}[LinearPDE]{getFunctionSpaceForSolution}{}
159     returns \FunctionSpace of the solution of the PDE hich is identical to \FunctionSpace of
160     the result of argument of the PDE operator.
161     \end{methoddesc}
162    
163     \begin{methoddesc}[LinearPDE]{setDebugOn}{}
164     switches the debug mode to on.
165     \end{methoddesc}
166    
167     \begin{methoddesc}[LinearPDE]{setDebugOff}{}
168     switches the debug mode to on.
169     \end{methoddesc}
170    
171     \begin{methoddesc}[LinearPDE]{debug}{}
172     returns \True if the debug mode is switched on. Otherwise it return \False.
173     \end{methoddesc}
174    
175     \begin{methoddesc}[LinearPDE]{setLumpingOn}{}
176     switches on lumping \index{lumping}. If lumping is switched on
177     the operator is
178     \end{methoddesc}
179    
180    
181     \begin{methoddesc}[LinearPDE]{setLumpingOff}
182     switches lumping off \index{lumping}.
183     \end{methoddesc}
184    
185     \begin{methoddesc}[LinearPDE]{setLumping}{flag=\False}
186     switches on lumping if \var{flag} is \True. Otherwise lumping is swiched off.
187     \end{methoddesc}
188    
189     \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
190     returns \True if lumping is switched on. Otherwise \False is returned.
191     \end{methoddesc}
192    
193     \begin{memberdesc}[LinearPDE]{DEFAULT_METHOD}
194     default method to be used to solve the PDE. An appropriate method should be
195     chosen by the used PDE solver library.
196     \end{memberdesc}
197    
198     \begin{memberdesc}[LinearPDE]{DIRECT}
199     direct linear solver~\Ref{SAAD}
200     \end{memberdesc}
201    
202     \begin{memberdesc}[LinearPDE]{CHOLEVSKY}
203     direct solver based on Cholevsky factorization (or similar), see~\Ref{SAAD}. The solver will require a symmetric PDE.
204     \end{memberdesc}
205    
206     \begin{memberdesc}[LinearPDE]{PCG}
207     preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.
208     \end{memberdesc}
209    
210     \begin{memberdesc}[LinearPDE]{GMRES}
211     the GMRES method, see~\Ref{WEISS}. Truncation and restart ar econtrolled by the parameters
212     \var{truncation} and \var{restart} of \method{getSolution}.
213     \end{memberdesc}
214    
215     \begin{memberdesc}[LinearPDE]{PRES20}
216     the GMRES method with trunction after five residuals and
217     restart after 20 steps, see~\Ref{WEISS}.
218     \end{memberdesc}
219    
220     \begin{memberdesc}[LinearPDE]{CR}
221     conjugate residual method, see~\Ref{WEISS}.
222     \end{memberdesc}
223    
224     \begin{memberdesc}[LinearPDE]{CGS}
225     conjugate gradient squared method, see~\Ref{WEISS}.
226     \end{memberdesc}
227    
228     \begin{memberdesc}[LinearPDE]{BICGSTAB}
229     stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.
230     \end{memberdesc}
231    
232     \begin{memberdesc}[LinearPDE]{SSOR}
233     symmetric successive overrelaxtion method, see~\Ref{WEISS}.
234     \end{memberdesc}
235    
236     \begin{methoddesc}[LinearPDE]{setSolverMethod}{solver=linearPDE.DEFAULT_METHOD}
237     sets the solver method to be used. It is pointed out that the PDE solver library
238     does not know the specified solver method but may choose a similar method.
239     \end{methoddesc}
240    
241     \begin{methoddesc}[LinearPDE]{setTolerance}{tol=1.e-8}
242     resets the tolerance for solution. The actually meaning of tolerance is
243     depending on the underlying PDE library. In most cases, the tolerance
244     will only consider the error from solving the discerete problem but will
245     not consider any discretization error.
246     \end{methoddesc}
247    
248     \begin{methoddesc}[LinearPDE]{getTolerance}{}
249     returns the current tolerance of the solution
250     \end{methoddesc}
251    
252     \begin{methoddesc}[LinearPDE]{isSymmetric}{}
253     returns \True if the PDE has been indicated to be symmetric.
254     Otherwise \False is returned.
255     \end{methoddesc}
256    
257     \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
258     indicates that the PDE is symmetric.
259     \end{methoddesc}
260    
261     \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
262     indicates that the PDE is not symmetric.
263     \end{methoddesc}
264    
265     \begin{methoddesc}[LinearPDE]{setSymmetryTo}{flag=\False}
266     indicates that the PDE is symmetric if \var{flag}=\True
267     and indicates a non-symmetric PDE is \var{flag}=\False.
268     \end{methoddesc}
269    
270     \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
271     switches on the reduction of polynomial order for the solution and
272     equation evaluation.
273     \end{methoddesc}
274    
275     \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
276     switches off the reduction of polynomial order for the solution and
277     equation evaluation.
278     \end{methoddesc}
279    
280     \begin{methoddesc}[LinearPDE]{setReducedOrderTo}{flag=\False}
281     switches on the reduction of polynomial order for the solution and
282     equation evaluation if \var{flag}=\True. Otherwise
283     the order reduction is switched off.
284     \end{methoddesc}
285    
286     \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionOn}{}
287     switches on reduction of polynomial order for the solution.
288     \end{methoddesc}
289    
290     \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionOff}{}
291     switches off reduction of polynomial order for the solution.
292     \end{methoddesc}
293    
294     \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionTo}{flag=\False}
295     switches on the reduction of polynomial order for the solution
296     if \var{flag}=\True. Otherwise
297     the order reduction is switched off.
298     \end{methoddesc}
299    
300     \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationOn}{}
301     switches on reduction of polynomial order for the equation evaluation.
302     \end{methoddesc}
303    
304     \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationOff}{}
305     switches off reduction of polynomial order for the equation evaluation.
306     \end{methoddesc}
307    
308     \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationTo}{flag=\False}
309     switches on the reduction of polynomial order for the equation
310     evaluation if \var{flag}=\True. Otherwise
311     the order reduction is switched off.
312     \end{methoddesc}
313    
314     \begin{methoddesc}[LinearPDE]{getOperator}{}
315     returns the \Operator of the PDE.
316     \end{methoddesc}
317    
318     \begin{methoddesc}[LinearPDE]{getRightHandSide}{ignoreConstraint=\False}
319     returns the right hand side of the PDE as a \Data object. If
320     \var{ignoreConstraint}=\True the constraints are not considered
321     when building up the right hand side.
322     \end{methoddesc}
323    
324     \begin{methoddesc}[LinearPDE]{getSystem}{}
325     returns the \Operator and right hand side of the PDE.
326     \end{methoddesc}
327    
328     \begin{methoddesc}[LinearPDE]{getSolution}{option1,option2,...,optionN}
329     returns (an approximation of) the solution of the PDE. \var{options1}, \var{options2}
330     $\ldots$ \var{optionsN} are options handed over to the underlying PDE solver library.
331     \end{methoddesc}
332    
333     \begin{methoddesc}[LinearPDE]{getDomain}{}
334     returns the \Domain of the PDE.
335     \end{methoddesc}
336    
337     \begin{methoddesc}[LinearPDE]{getDim}{}
338     returns the spatial dimension of the PDE.
339     \end{methoddesc}
340    
341     \begin{methoddesc}[LinearPDE]{getNumEquations}{}
342     returns the number of equations.
343     \end{methoddesc}
344    
345     \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
346     returns the number of components of the solution.
347     \end{methoddesc}
348    
349     \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
350     returns \True if the PDE is symmetric and \False otherwise.
351     The method is very computational expensive and should only be
352     called for testing purposes. The symmetry flag is not altered.
353     If \var{verbose}=\True information about where symmetry is violated
354     are printed.
355     \end{methoddesc}
356    
357     \begin{methoddesc}[LinearPDE]{getFlux}{u}
358     returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}
359     defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
360     \end{methoddesc}
361    
362     \begin{methoddesc}[LinearPDE]{applyOperator}{u}
363     applies the PDE operator to \var{u}
364     \end{methoddesc}
365    
366     \begin{methoddesc}[LinearPDE]{getResidual}{u}
367     returns the residual when insering \var{u} into the PDE
368     \end{methoddesc}
369    
370     \section{\AdvectivePDE Class}
371     under construction
372    
373     \section{The \Poisson Class}
374    
375     The \Poisson class provides an easy way to define and solve the Poisson
376     equation
377     \begin{equation}\label{POISSON.1}
378     -u\hackscore{,ii}=f\; .
379     \end{equation}
380     with homogeneous boundary conditions
381     \begin{equation}\label{POISSON.2}
382     n\hackscore{i}u\hackscore{,i}=0
383     \end{equation}
384     and homogeneous constraints
385     \begin{equation}\label{POISSON.3}
386     u=0 \mbox{ where } q>0
387     \end{equation}
388     $f$ has to be a \Scalar in the \Function and $q$ must be
389     a \Scalar in the \SolutionFS.
390    
391     \begin{classdesc}{Poisson}{domain}
392     opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
393     \end{classdesc}
394     \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
395     assigns new values to \var{f} and \var{q}.
396     \end{methoddesc}

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26