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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 624 by gross, Fri Mar 17 05:48:59 2006 UTC revision 625 by gross, Thu Mar 23 00:41:25 2006 UTC
# Line 1  Line 1 
1  % $Id$  % $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}  \chapter{The module \linearPDEs}
12    
# Line 24  the outer normal field on $\Gamma$. Line 32  the outer normal field on $\Gamma$.
32  For a single PDE with a solution with a single component the linear PDE is defined in the  For a single PDE with a solution with a single component the linear PDE is defined in the
33  following form:  following form:
34  \begin{equation}\label{LINEARPDE.SINGLE.1}  \begin{equation}\label{LINEARPDE.SINGLE.1}
35  -(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 \; .  -(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}  \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.  $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  The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through \Data objects in the
# Line 44  u=r \mbox{ where } q>0 Line 52  u=r \mbox{ where } q>0
52  $r$ and $q$ are each \Scalar where $q$ is the characteristic function  $r$ and $q$ are each \Scalar where $q$ is the characteristic function
53  \index{characteristic function} defining where the constraint is applied.  \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}  The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other condition set by \eqn{LINEARPDE.SINGLE.1}
55  or \eqn{LINEARPDE.SINGLE.2}. The PDE is symmetrical \index{symmetrical} if  or \eqn{LINEARPDE.SINGLE.2}.
56  \begin{equation}\label{LINEARPDE.SINGLE.4}  
 A\hackscore{jl}=A\hackscore{lj} \mbox{ and } B\hackscore{j}=C\hackscore{j}  
 \end{equation}  
57  For a system of PDEs and a solution with several components the PDE has the form  For a system of PDEs and a solution with several components the PDE has the form
58  \begin{equation}\label{LINEARPDE.SYSTEM.1}  \begin{equation}\label{LINEARPDE.SYSTEM.1}
59  -(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} \; .  -(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}  \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.  $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:  The natural boundary conditions \index{boundary condition!natural} take the form:
63  \begin{equation}\label{LINEARPDE.SYSTEM.2}  \begin{equation}\label{LINEARPDE.SYSTEM.2}
64  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}  \;.  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}  \end{equation}
66  The coefficient $d$ is a \RankTwo and $y$ is a    The coefficient $d$ is a \RankTwo and $y$ is a  
67  \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form  \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form
68  \begin{equation}\label{LINEARPDE.SYSTEM.3}  \begin{equation}\label{LINEARPDE.SYSTEM.3}
69  u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0  u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
70  \end{equation}  \end{equation}
71  $r$ and $q$ are each \RankOne. Notice that at some locations not necessarily all components must  $r$ and $q$ are each \RankOne. Notice that not necessarily all components must
72  have a constraint. The system of PDEs is symmetrical \index{symmetrical} if  have a constraint at all locations.
73  \begin{eqnarray}\label{LINEARPDE.SYSTEM.4}  
 A\hackscore{ijkl}=A\hackscore{klij} \\  
 B\hackscore{ijk}=C\hackscore{kij} \\  
 D\hackscore{ik}=D\hackscore{ki} \\  
 d\hackscore{ik}=d\hackscore{ki} \  
 \end{eqnarray}  
74  \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$  \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  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  generalised flux $J$ which is in the case of a systems of PDEs and several components of the solution
# Line 98  n\hackscore{j} J^{0}\hackscore{j}=n\hack Line 99  n\hackscore{j} J^{0}\hackscore{j}=n\hack
99  \end{equation}  \end{equation}
100  In this case the the coefficient $d^{contact}$ and $y^{contact}$ are eaach \Scalar  In this case the the coefficient $d^{contact}$ and $y^{contact}$ are eaach \Scalar
101  both in the \FunctionOnContactZero or \FunctionOnContactOne.  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}  \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
124  opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}  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.  and \var{numSolutions} gives the number of equations and the number of solutiopn components.
# Line 107  and the number solutions, respctively, s Line 128  and the number solutions, respctively, s
128  defined.  defined.
129  \end{classdesc}  \end{classdesc}
130    
131  \begin{methoddesc}[LinearPDE]{setValues}{arg1,arg2,...,argN}  \begin{methoddesc}[LinearPDE]{setValue}{
132  assigns new values to coefficients \var{arg1}, \var{arg2}, $\ldots$ \var{argN}.  \optional{A=Data()}\optional{, B=Data()},
133  The coefficients must be one of the valid coefficient names  \optional{, C=Data()}\optional{, D=Data()}
134  \var{A},  \optional{, X=Data()}\optional{, Y=Data()}
135  \var{B},  \optional{, d=Data()}\optional{, y=Data()}
136  \var{C},  \optional{, d_contact=Data()}\optional{, y_contact=Data()}
137  \var{D},  \optional{, q=Data()}\optional{, r=Data()}}
138  \var{X},  assigns new values to coefficients.
139  \var{Y},  If the new coefficient value is not a \Data object, it is converted into a \Data object in the
 \var{d},  
 \var{y},  
 \var{dcontact},  
 \var{ycontact},  
 \var{r},  
 or \var{q}.  
 If the coefficient is not a \Data object, it is converted into a \Data object in the  
140  appropriate \FunctionSpace.  appropriate \FunctionSpace.
141  \end{methoddesc}  \end{methoddesc}
142    
 \begin{methoddesc}[LinearPDE]{createCoefficient}{name}  
 facilitates the creation of a \Data object corresponding to coefficient of name  
 \var{name}. If \var{name} is not a valid name an exception is raised. The  
 returned \Data object is initialised to zero and is not set as a value of the  
 LinearPDE.  
 \end{methoddesc}  
   
143  \begin{methoddesc}[LinearPDE]{getCoefficient}{name}  \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
144  return the value assigned to coefficient \var{name}. If \var{name} is not a valid name  return the value assigned to coefficient \var{name}. If \var{name} is not a valid name
145  an exception is raised.  an exception is raised.
146  \end{methoddesc}  \end{methoddesc}
147    
 \begin{methoddesc}[LinearPDE]{cleanCoefficients}{}  
 resets all coefficients to their initialization values. This method is useful to call when trying to save memory  
 as is releaces eqnerences to coefficients but keeping the differential operator.  
 \end{methoddesc}  
 \begin{methoddesc}[LinearPDE]{createNewCoefficient}{name}  
 returns a \Data object which has the \FunctionSpace and \Shape of coefficient \var{name}. The initial value is $0$.  
 \end{methoddesc}  
   
148  \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}  \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
149  returns the shape of coefficient \var{name} even if no value has been assigned to it.  returns the shape of coefficient \var{name} even if no value has been assigned to it.
150  \end{methoddesc}  \end{methoddesc}
151    
152    \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
 \begin{methoddesc}[LinearPDE]{getFunctionSpaceOfCoefficient}{name}  
153  returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.  returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.
154  \end{methoddesc}  \end{methoddesc}
155    
 \begin{methoddesc}[LinearPDE]{hasCoefficient}{name}  
 returns \True if \var{name} is valid name of a coefficient  
 \end{methoddesc}  
   
   
 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForEquation}{}  
 returns \FunctionSpace of the right hand side which is identical to \FunctionSpace of  
 the result of the PDE operator.  
 \end{methoddesc}  
   
 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForSolution}{}  
 returns \FunctionSpace of the solution of the PDE hich is identical to \FunctionSpace of  
 the result of argument of the PDE operator.  
 \end{methoddesc}  
   
156  \begin{methoddesc}[LinearPDE]{setDebugOn}{}  \begin{methoddesc}[LinearPDE]{setDebugOn}{}
157  switches the debug mode to on.  switches the debug mode to on.
158  \end{methoddesc}  \end{methoddesc}
# Line 178  switches the debug mode to on. Line 161  switches the debug mode to on.
161  switches the debug mode to on.  switches the debug mode to on.
162  \end{methoddesc}  \end{methoddesc}
163    
 \begin{methoddesc}[LinearPDE]{debug}{}  
 returns \True if the debug mode is switched on. Otherwise it return \False.  
 \end{methoddesc}  
   
 \begin{methoddesc}[LinearPDE]{setLumpingOn}{}  
 switches on lumping \index{lumping}. If lumping is switched on  
 the operator is  
 \end{methoddesc}  
   
   
 \begin{methoddesc}[LinearPDE]{setLumpingOff}  
 switches lumping off \index{lumping}.  
 \end{methoddesc}  
   
 \begin{methoddesc}[LinearPDE]{setLumping}{flag=\False}  
 switches on lumping if \var{flag} is \True. Otherwise lumping is swiched off.  
 \end{methoddesc}  
   
164  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
165  returns \True if lumping is switched on. Otherwise \False is returned.  returns \True if lumping is switched on. Otherwise \False is returned.
166  \end{methoddesc}  \end{methoddesc}
167    
168  \begin{memberdesc}[LinearPDE]{DEFAULT_METHOD}  \begin{methoddesc}[LinearPDE]{setSolverMethod}{\optional{solver=LinearPDE.DEFAULT}\options{, preconditioner=LinearPDE.DEFAULT})
169  default method to be used to solve the PDE. An appropriate method should be  sets the solver method and preconditioner to be used. It is pointed out that a PDE solver library
170  chosen by the used PDE solver library.  may not know the specified solver method but may choose a similar method and preconditioner.
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{DIRECT}  
 direct linear solver~\Ref{SAAD}  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{CHOLEVSKY}  
 direct solver based on Cholevsky factorization (or similar), see~\Ref{SAAD}. The solver will require a symmetric PDE.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{PCG}  
 preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{GMRES}  
 the GMRES method, see~\Ref{WEISS}. Truncation and restart ar econtrolled by the parameters  
 \var{truncation} and \var{restart} of \method{getSolution}.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{PRES20}  
 the GMRES method with trunction after five residuals and  
 restart after 20 steps, see~\Ref{WEISS}.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{CR}  
 conjugate residual method, see~\Ref{WEISS}.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{CGS}  
 conjugate gradient squared method, see~\Ref{WEISS}.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{BICGSTAB}  
 stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.  
 \end{memberdesc}  
   
 \begin{memberdesc}[LinearPDE]{SSOR}  
 symmetric successive overrelaxtion method, see~\Ref{WEISS}.  
 \end{memberdesc}  
   
 \begin{methoddesc}[LinearPDE]{setSolverMethod}{solver=linearPDE.DEFAULT_METHOD}  
 sets the solver method to be used. It is pointed out that the PDE solver library  
 does not know the specified solver method but may choose a similar method.  
171  \end{methoddesc}  \end{methoddesc}
172    
173  \begin{methoddesc}[LinearPDE]{setTolerance}{tol=1.e-8}  \begin{methoddesc}[LinearPDE]{setTolerance}{\optional{tol=1.e-8}}:
174  resets the tolerance for solution. The actually meaning of tolerance is  resets the tolerance for solution. The actually meaning of tolerance is
175  depending on the underlying PDE library. In most cases, the tolerance  depending on the underlying PDE library. In most cases, the tolerance
176  will only consider the error from solving the discerete problem but will  will only consider the error from solving the discerete problem but will
# Line 259  not consider any discretization error. Line 181  not consider any discretization error.
181  returns the current tolerance of the solution  returns the current tolerance of the solution
182  \end{methoddesc}  \end{methoddesc}
183    
184  \begin{methoddesc}[LinearPDE]{isSymmetric}{}  \begin{methoddesc}[LinearPDE]{getDomain}{}
185  returns \True if the PDE has been indicated to be symmetric.  returns the \Domain of the PDE.
 Otherwise \False is returned.  
 \end{methoddesc}  
   
 \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}  
 indicates that the PDE is symmetric.  
186  \end{methoddesc}  \end{methoddesc}
187    
188  \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}  \begin{methoddesc}[LinearPDE]{getDim}{}
189  indicates that the PDE is not symmetric.  returns the spatial dimension of the PDE.
190  \end{methoddesc}  \end{methoddesc}
191    
192  \begin{methoddesc}[LinearPDE]{setSymmetryTo}{flag=\False}  \begin{methoddesc}[LinearPDE]{getNumEquations}{}
193  indicates that the PDE is symmetric if \var{flag}=\True  returns the number of equations.
 and indicates a non-symmetric PDE is \var{flag}=\False.  
194  \end{methoddesc}  \end{methoddesc}
195    
196  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}  \begin{methoddesc}[LinearPDE]{getNumSolutions}{}
197  switches on the reduction of polynomial order for the solution and  returns the number of components of the solution.
 equation evaluation.  
198  \end{methoddesc}  \end{methoddesc}
199    
200  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
201  switches off the reduction of polynomial order for the solution and  returns \True if the PDE is symmetric and \False otherwise.
202  equation evaluation.  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}  \end{methoddesc}
207    
208  \begin{methoddesc}[LinearPDE]{setReducedOrderTo}{flag=\False}  \begin{methoddesc}[LinearPDE]{getFlux}{u}
209  switches on the reduction of polynomial order for the solution and  returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}
210  equation evaluation if \var{flag}=\True. Otherwise  defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
 the order reduction is switched off.  
211  \end{methoddesc}  \end{methoddesc}
212    
213  \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionOn}{}  \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}
214  switches on reduction of polynomial order for the solution.  \begin{methoddesc}[LinearPDE]{getSolverMethod}{}
215  \end{methoddesc}  \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=None}}
216    \begin{methoddesc}[LinearPDE]{getSolverPackage}{}
217    
218  \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionOff}{}  \begin{methoddesc}[LinearPDE]{isSymmetric}{}
219  switches off reduction of polynomial order for the solution.  returns \True if the PDE has been indicated to be symmetric.
220    Otherwise \False is returned.
221  \end{methoddesc}  \end{methoddesc}
222    
223  \begin{methoddesc}[LinearPDE]{setReducedOrderForSolutionTo}{flag=\False}  \begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
224  switches on the reduction of polynomial order for the solution  indicates that the PDE is symmetric.
 if \var{flag}=\True. Otherwise  
 the order reduction is switched off.  
225  \end{methoddesc}  \end{methoddesc}
226    
227  \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationOn}{}  \begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
228  switches on reduction of polynomial order for the equation evaluation.  indicates that the PDE is not symmetric.
229  \end{methoddesc}  \end{methoddesc}
230    
231  \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationOff}{}  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
232  switches off reduction of polynomial order for the equation evaluation.  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}  \end{methoddesc}
236    
237  \begin{methoddesc}[LinearPDE]{setReducedOrderForEquationTo}{flag=\False}  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
238  switches on the reduction of polynomial order for the equation  switches off the reduction of polynomial order for the solution and
239  evaluation if \var{flag}=\True. Otherwise  equation evaluation.
 the order reduction is switched off.  
240  \end{methoddesc}  \end{methoddesc}
241    
242  \begin{methoddesc}[LinearPDE]{getOperator}{}  \begin{methoddesc}[LinearPDE]{getOperator}{}
243  returns the \Operator of the PDE.  returns the \Operator of the PDE.
244  \end{methoddesc}  \end{methoddesc}
245    
246  \begin{methoddesc}[LinearPDE]{getRightHandSide}{ignoreConstraint=\False}  \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
247  returns the right hand side of the PDE as a \Data object. If  returns the right hand side of the PDE as a \Data object. If
248  \var{ignoreConstraint}=\True the constraints are not considered  \var{ignoreConstraint}=\True the constraints are not considered
249  when building up the right hand side.  when building up the right hand side.
# Line 335  when building up the right hand side. Line 253  when building up the right hand side.
253  returns the \Operator and right hand side of the PDE.  returns the \Operator and right hand side of the PDE.
254  \end{methoddesc}  \end{methoddesc}
255    
256  \begin{methoddesc}[LinearPDE]{getSolution}{option1,option2,...,optionN}  \begin{methoddesc}[LinearPDE]{getSolution}{
257  returns (an approximation of) the solution of the PDE. \var{options1},  \var{options2}  \optional{verbose=False}
258  $\ldots$ \var{optionsN} are options handed over to the underlying PDE solver library.    \optional{, reordering=LinearPDE.NO_REORDERING}
259  \end{methoddesc}  \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{methoddesc}[LinearPDE]{getDomain}{}  \begin{memberdesc}[LinearPDE]{SCSL}
281  returns the \Domain of the PDE.  \end{memberdesc}
 \end{methoddesc}  
282    
283  \begin{methoddesc}[LinearPDE]{getDim}{}  \begin{memberdesc}[LinearPDE]{MKL}
284  returns the spatial dimension of the PDE.  \end{memberdesc}
 \end{methoddesc}  
285    
286  \begin{methoddesc}[LinearPDE]{getNumEquations}{}  \begin{memberdesc}[LinearPDE]{UMFPACK}
287  returns the number of equations.  \end{memberdesc}
 \end{methoddesc}  
288    
289  \begin{methoddesc}[LinearPDE]{getNumSolutions}{}  \begin{memberdesc}[LinearPDE]{PASO}
290  returns the number of components of the solution.  \end{memberdesc}
 \end{methoddesc}  
291    
292  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}  \begin{memberdesc}[LinearPDE]{ITERATIVE}
 returns \True if the PDE is symmetric and \False otherwise.  
 The method is very computational expensive and should only be  
 called for testing purposes. The symmetry flag is not altered.  
 If \var{verbose}=\True information about where symmetry is violated  
 are printed.  
 \end{methoddesc}  
293    
294  \begin{methoddesc}[LinearPDE]{getFlux}{u}  \end{memberdesc}
 returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}  
 defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.  
 \end{methoddesc}  
295    
296  \begin{methoddesc}[LinearPDE]{applyOperator}{u}  \begin{memberdesc}[LinearPDE]{DIRECT}
297  applies the PDE operator to \var{u}  direct linear solver~\Ref{SAAD}
298  \end{methoddesc}  \end{memberdesc}
299    
300  \begin{methoddesc}[LinearPDE]{getResidual}{u}  \begin{memberdesc}[LinearPDE]{CHOLEVSKY}
301  returns the residual when insering \var{u} into the PDE  direct solver based on Cholevsky factorization (or similar), see~\Ref{SAAD}. The solver will require a symmetric PDE.
302  \end{methoddesc}  \end{memberdesc}
303    
304  \section{\AdvectivePDE Class}  \begin{memberdesc}[LinearPDE]{PCG}
305  In cases of PDEs dominated by the advection terms $B$ and $C$ against the diffusion term $A$  preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.
306  up-winding has been used.  \end{memberdesc}
 The \AdvectivePDE class applies upwinding to the advective terms, see \Ref{SUPG}.  
307    
308  In the following we set  \begin{memberdesc}[LinearPDE]{GMRES}
309  \begin{eqnarray}\label{LINEARPDE.UPWIND.Z}  the GMRES method, see~\Ref{WEISS}. Truncation and restart ar econtrolled by the parameters
310  Z\hackscore{j}=C\hackscore{j}-B\hackscore{j}  \var{truncation} and \var{restart} of \method{getSolution}.
311  \mbox{ or } \\  \end{memberdesc}
 Z\hackscore{ikl}=C\hackscore{ikl}-B\hackscore{ilk}  
 \end{eqnarray}  
 To measure the dominance of the advective terms over the diffusive term $A$ the  
 Pelclet number is used \index{Pelclet number}. The are defined as  
 \begin{eqnarray}\label{LINEARPDE.Peclet.single}  
 P=\frac{h\|Z\hackscore{:}\|}{2\|A\hackscore{::}\|}  
 \end{eqnarray}  
 \begin{eqnarray}\label{LINEARPDE.Peclet.system}  
 P\hackscore{ik}=\frac{h\|Z\hackscore{i:k}\|}{2\|A\hackscore{i:k:}\|}  
 \end{eqnarray}  
 where $h$ is the local cell size and  
 \begin{eqnarray}\label{LINEARPDE.ADVECTIVE.1b}  
 \|Z\hackscore{:}\|^2=Z\hackscore{j}Z\hackscore{j} \\  
 \|A\hackscore{::}\|^2=A\hackscore{jl}A\hackscore{jl} \\  
 \|Z\hackscore{i:k}\|^2=\delta\hackscore{in} \delta\hackscore{km} Z\hackscore{njm}Z\hackscore{njm} \\  
 \|A\hackscore{i:k:}\|^2=\delta\hackscore{in} \delta\hackscore{km} A\hackscore{njml}A\hackscore{njml} \; .  
 \end{eqnarray}  
 In the case that it is $\|A\hackscore{::}\|$ we set $P=0$ if $\|Z\hackscore{:}\|=0$ and  
 $P=\infinity$ if $\|Z\hackscore{:}\|=0$. Analogously for $P$ in the case of a systems of PDEs.  
312    
313  From the Pelclet number the stabilization parameters $\Xi$ and $\Xi$ are calculated:  \begin{memberdesc}[LinearPDE]{LUMPING}
314  \begin{eqnarray}\label{LINEARPDE.Peclet.2}  conjugate residual method, see~\Ref{WEISS}.
315  \Xi=\xi(P) \frac{h}{\|Z\hackscore{:}\|}  \\  \end{memberdesc}
 \mbox{ or } \\  
 \Xi\hackscore{ik}=\xi(P\hackscore{ik}) \frac{h}{\|Z\hackscore{i:k}\|}  
 \end{eqnarray}  
 where $\xi$ is a suitable function of the Peclet number.  
 In the case of a single PDE the coefficient are up-dated in the following way:  
 \begin{eqnarray}\label{LINEARPDE.ADVECTIVE.1}  
 A\hackscore{jl} \leftarrow A\hackscore{jl} + \Xi Z\hackscore{j} Z\hackscore{l} \\  
 B\hackscore{j} \leftarrow B\hackscore{j} + \Xi C\hackscore{j} D \\  
 C\hackscore{j} \leftarrow C\hackscore{j} + \Xi B\hackscore{j} D \\  
 X\hackscore{j} \leftarrow X\hackscore{j} + \Xi Z\hackscore{j} Y \\  
 \end{eqnarray}  
 Similar for the case of a systems of PDEs:  
 \begin{eqnarray}\label{LINEARPDE.ADVECTIVE.SYSTEM}  
 A\hackscore{ijkl} \leftarrow A\hackscore{ijl} + \delta\hackscore{pm} \Xi\hackscore{mi} Z\hackscore{pij} Z\hackscore{mkl} \\  
 B\hackscore{ijk} \leftarrow B\hackscore{ijk} +  \delta\hackscore{pm} \Xi\hackscore{mi} D\hackscore{pk} C\hackscore{mij} \\  
 C\hackscore{ikl} \leftarrow C\hackscore{ikl} +  \delta\hackscore{pm} \Xi\hackscore{mi} D\hackscore{pk} B\hackscore{mli} \\  
 X\hackscore{ij} \leftarrow X\hackscore{ij} + \delta\hackscore{pm} \Xi\hackscore{mi}  Y\hackscore{p} Z\hackscore{mij}\\  
 \end{eqnarray}  
 Using upwinding in this form, introduces an additonal error which is proprtional to the cell size $h$  
 but with the intension to stabilize the solution.  
316    
317  \begin{classdesc}{AdvectivePDE}{domain,numEquations=0,numSolutions=0,xi=AdvectivePDE.ELMAN_RAMAGE}  \begin{memberdesc}[LinearPDE]{PRES20}
318  opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}  the GMRES method with trunction after five residuals and
319  and \var{numSolutions} gives the number of equations and the number of solutiopn components.  restart after 20 steps, see~\Ref{WEISS}.
 If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations  
 and the number solutions, respectively, stay undefined until a coefficient is  
 defined. \var{xi} defines a function which returns for any given  Preclet number $P\ge 0$ the  
 $\xi$-value used to define the stabilization parameters $\Xi$ and $\Xi$.  
 \AdvectivePDE is derived from \LinearPDE.  
 \end{classdesc}  
320    
321  \begin{memberdesc}[AdvectivePDE]{SIMPLIFIED_BROOKS_HUGHES}{}  \begin{memberdesc}[LinearPDE]{CR}
322  Predefined function to set a values for $\xi$ from a Preclet number $P$.  
323  This function uses the method suggested in \Ref{SUPG1}  \begin{memberdesc}[LinearPDE]{CGS}
324  where $\xi(P)$ is given by  conjugate gradient squared method, see~\Ref{WEISS}.
 \begin{equation}\label{LINEARPDE.ADVECTIVE.1d}  
 \xi(P)=coth(P)-\frac{1}{P} \;.  
 \end{equation}  
 As the evaluation of $coth$ is expensive we are using the approximation:  
 The function $\xi$ is approximated by  
 \begin{equation}\label{LINEARPDE.ADVECTIVE.23}  
 \xi(P)=  
 \left\{  
 \begin{array}{lc}  
 \frac{P}{6} & P<3 \\  
 \frac{1}{2} & \mbox{otherwise}  
 \end{array}  
 \right.  
 \end{equation}  
325  \end{memberdesc}  \end{memberdesc}
326    
327  \begin{memberdesc}[AdvectivePDE]{ELMAN_RAMAGE}{}  \begin{memberdesc}[LinearPDE]{BICGSTAB}
328  Predefined function to set a values for $\xi$ from a Preclet number $P$.  stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.
 This function uses the method suggested in \Ref{SUPG2}  
 where $\xi(P)$ is given by  
 \begin{equation}\label{LINEARPDE.ADVECTIVE.23b}  
 \xi(P)=  
 \left\{  
 \begin{array}{lc}  
 0  & P<1 \\  
 \frac{1}{2}(1-\frac{1}{P}) & \mbox{otherwise}  
 \end{array}  
 \right.  
 \end{equation}  
329  \end{memberdesc}  \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    
 \section{The \Poisson Class}  
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  The \Poisson class provides an easy way to define and solve the Poisson
355  equation  equation
356  \begin{equation}\label{POISSON.1}  \begin{equation}\label{POISSON.1}
# Line 500  opens a Poisson equation on the \Domain Line 373  opens a Poisson equation on the \Domain
373  \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}  \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
374  assigns new values to \var{f} and \var{q}.  assigns new values to \var{f} and \var{q}.
375  \end{methoddesc}  \end{methoddesc}
376    
377    \section{The \Helmholtz Class}
378    
379    \section{The \Lame Class}
380    

Legend:
Removed from v.624  
changed lines
  Added in v.625

  ViewVC Help
Powered by ViewVC 1.1.26