/[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 625 by gross, Thu Mar 23 00:41:25 2006 UTC revision 1700 by lgraham, Thu Aug 14 03:35:46 2008 UTC
# Line 1  Line 1 
1    %
2  % $Id$  % $Id$
3  %  %
4  %           Copyright © 2006 by ACcESS MNRF  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5  %               \url{http://www.access.edu.au  %
6  %         Primary Business: Queensland, Australia.  %           Copyright 2003-2007 by ACceSS MNRF
7  %   Licensed under the Open Software License version 3.0  %       Copyright 2007 by University of Queensland
8  %      http://www.opensource.org/licenses/osl-3.0.php  %
9    %                http://esscc.uq.edu.au
10    %        Primary Business: Queensland, Australia
11    %  Licensed under the Open Software License version 3.0
12    %     http://www.opensource.org/licenses/osl-3.0.php
13    %
14    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15  %  %
16    
17    \chapter{The Module \linearPDEs}
18    
 \chapter{The module \linearPDEs}  
19    
 \declaremodule{extension}{linearPDEs} \modulesynopsis{Linear partial pifferential equation handler}  
 The module \linearPDEs provides an interface to define and solve linear partial  
 differential equations within \escript. \linearPDEs does not provide any  
 solver capabilities in itself but hands the PDE over to  
 the PDE solver library defined through the \Domain of the PDE.  
 The general interface is provided through the \LinearPDE class. The  
 \AdvectivePDE which is derived from the \LinearPDE class  
 provides an interface to PDE dominated by its advective terms. The \Poisson  
 class which is also derived form the \LinearPDE class should be used  
 to define the Poisson equation \index{Poisson}.    
20    
21  \section{\LinearPDE Class}  \section{Linear Partial Differential Equations}
22  \label{SEC LinearPDE}  \label{SEC LinearPDE}
23    
24  The \LinearPDE class is used to define a general linear, steady, second order PDE  The \LinearPDE class is used to define a general linear, steady, second order PDE
25  for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.  for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.
26  In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes  In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes
27  the outer normal field on $\Gamma$.  the outer normal field on $\Gamma$.
28    
29  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
30  following form:  following form:
31  \begin{equation}\label{LINEARPDE.SINGLE.1}  \begin{equation}\label{LINEARPDE.SINGLE.1}
32  -(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 \; .  -(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 \; .
33  \end{equation}  \end{equation}
34  $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.
35  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
36  \Function on the PDE or objects that can be converted into such \Data objects.  \Function on the PDE or objects that can be converted into such \Data objects.
37  $A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar.  $A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar.
38  The following natural  The following natural
39  boundary conditions are considered \index{boundary condition!natural} on $\Gamma$:  boundary conditions are considered \index{boundary condition!natural} on $\Gamma$:
40  \begin{equation}\label{LINEARPDE.SINGLE.2}  \begin{equation}\label{LINEARPDE.SINGLE.2}
41  n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y  \;.  n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y  \;.
42  \end{equation}  \end{equation}
43  Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are    Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are
44  each a \Scalar in the \FunctionOnBoundary.  Constraints \index{constraint} for the solution prescribing the value of the  each a \Scalar in the \FunctionOnBoundary.  Constraints \index{constraint} for the solution prescribing the value of the
45  solution at certain locations in the domain. They have the form  solution at certain locations in the domain. They have the form
46  \begin{equation}\label{LINEARPDE.SINGLE.3}  \begin{equation}\label{LINEARPDE.SINGLE.3}
47  u=r \mbox{ where } q>0  u=r \mbox{ where } q>0
# Line 52  u=r \mbox{ where } q>0 Line 49  u=r \mbox{ where } q>0
49  $r$ and $q$ are each \Scalar where $q$ is the characteristic function  $r$ and $q$ are each \Scalar where $q$ is the characteristic function
50  \index{characteristic function} defining where the constraint is applied.  \index{characteristic function} defining where the constraint is applied.
51  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}
52  or \eqn{LINEARPDE.SINGLE.2}.  or \eqn{LINEARPDE.SINGLE.2}.
53    
54  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
55  \begin{equation}\label{LINEARPDE.SYSTEM.1}  \begin{equation}\label{LINEARPDE.SYSTEM.1}
56  -(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} \; .  -(A\hackscore{ijkl} u\hackscore{k,l})\hackscore{,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} \; .
57  \end{equation}  \end{equation}
58  $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.
59  The natural boundary conditions \index{boundary condition!natural} take the form:  The natural boundary conditions \index{boundary condition!natural} take the form:
60  \begin{equation}\label{LINEARPDE.SYSTEM.2}  \begin{equation}\label{LINEARPDE.SYSTEM.2}
61  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}  \;.  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}  \;.
62  \end{equation}  \end{equation}
63  The coefficient $d$ is a \RankTwo and $y$ is a    The coefficient $d$ is a \RankTwo and $y$ is a
64  \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form  \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form
65  \begin{equation}\label{LINEARPDE.SYSTEM.3}  \begin{equation}\label{LINEARPDE.SYSTEM.3}
66  u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0  u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
67  \end{equation}  \end{equation}
68  $r$ and $q$ are each \RankOne. Notice that not necessarily all components must  $r$ and $q$ are each \RankOne. Notice that not necessarily all components must
69  have a constraint at all locations.  have a constraint at all locations.
70    
71  \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$  \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$
72  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
73  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
74  defined as  defined as
75  \begin{equation}\label{LINEARPDE.SYSTEM.5}  \begin{equation}\label{LINEARPDE.SYSTEM.5}
76  J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij}  J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij}
77  \end{equation}  \end{equation}
# Line 82  For the case of single solution componen Line 79  For the case of single solution componen
79  \begin{equation}\label{LINEARPDE.SINGLE.5}  \begin{equation}\label{LINEARPDE.SINGLE.5}
80  J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j}  J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j}
81  \end{equation}  \end{equation}
82  In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the  In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the
83  discontinuity pointing from side 0 towards side 1. For a system of PDEs  discontinuity pointing from side 0 towards side 1. For a system of PDEs
84  the contact condition takes the form  the contact condition takes the form
85  \begin{equation}\label{LINEARPDE.SYSTEM.6}  \begin{equation}\label{LINEARPDE.SYSTEM.6}
# Line 91  n\hackscore{j} J^{0}\hackscore{ij}=n\hac Line 88  n\hackscore{j} J^{0}\hackscore{ij}=n\hac
88  where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the  where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the
89  discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference  discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference
90  of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.  of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.
91  The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a    The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a
92  \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.  \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.
93  In case of a single PDE and a single component solution the contact condition takes the form  In case of a single PDE and a single component solution the contact condition takes the form
94  \begin{equation}\label{LINEARPDE.SINGLE.6}  \begin{equation}\label{LINEARPDE.SINGLE.6}
95  n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u]  n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u]
96  \end{equation}  \end{equation}
97  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 each \Scalar
98  both in the \FunctionOnContactZero or \FunctionOnContactOne.  both in the \FunctionOnContactZero or \FunctionOnContactOne.
99    
100  The PDE is symmetrical \index{symmetrical} if  The PDE is symmetrical \index{symmetrical} if
# Line 111  A\hackscore{ijkl}=A\hackscore{klij} \\ Line 108  A\hackscore{ijkl}=A\hackscore{klij} \\
108  B\hackscore{ijk}=C\hackscore{kij} \\  B\hackscore{ijk}=C\hackscore{kij} \\
109  D\hackscore{ik}=D\hackscore{ki} \\  D\hackscore{ik}=D\hackscore{ki} \\
110  d\hackscore{ik}=d\hackscore{ki} \\  d\hackscore{ik}=d\hackscore{ki} \\
111  d^{contact}\hackscore{ik}=d^{contact}\hackscore{ki}  d^{contact}\hackscore{ik}=d^{contact}\hackscore{ki}
112  \end{eqnarray}  \end{eqnarray}
113  Note that different from the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$  Note that different from the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$
114  have to be inspected.  have to be inspected.
115    
116  \section{\LinearPDE class}  
117  This is the general class to define a linear PDE in \escript. We list a selction of the most  \subsection{Classes}
118    \declaremodule{extension}{esys.escript.linearPDEs}
119    \modulesynopsis{Linear partial differential equation handler}
120    The module \linearPDEs provides an interface to define and solve linear partial
121    differential equations within \escript. \linearPDEs does not provide any
122    solver capabilities in itself but hands the PDE over to
123    the PDE solver library defined through the \Domain of the PDE.
124    The general interface is provided through the \LinearPDE class. The
125    \AdvectivePDE which is derived from the \LinearPDE class
126    provides an interface to PDE dominated by its advective terms. The \Poisson
127    class which is also derived form the \LinearPDE class should be used
128    to define the Poisson equation \index{Poisson}.
129    
130    \subsection{\LinearPDE class}
131    This is the general class to define a linear PDE in \escript. We list a selection of the most
132  important methods of the class only and refer to reference guide \ReferenceGuide for a complete list.  important methods of the class only and refer to reference guide \ReferenceGuide for a complete list.
133    
134  \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}  \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
135  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}
136  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 solution components.
137  If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations  If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations
138  and the number solutions, respctively, stay undefined until a coefficient is  and the number solutions, respectively, stay undefined until a coefficient is
139  defined.  defined.
140  \end{classdesc}  \end{classdesc}
141    
142  \begin{methoddesc}[LinearPDE]{setValue}{  \begin{methoddesc}[LinearPDE]{setValue}{
143  \optional{A=Data()}\optional{, B=Data()},  \optional{A}\optional{, B},
144  \optional{, C=Data()}\optional{, D=Data()}  \optional{, C}\optional{, D}
145  \optional{, X=Data()}\optional{, Y=Data()}  \optional{, X}\optional{, Y}
146  \optional{, d=Data()}\optional{, y=Data()}  \optional{, d}\optional{, y}
147  \optional{, d_contact=Data()}\optional{, y_contact=Data()}  \optional{, d_contact}\optional{, y_contact}
148  \optional{, q=Data()}\optional{, r=Data()}}  \optional{, q}\optional{, r}}
149  assigns new values to coefficients.  assigns new values to coefficients. By default all values are assumed to be zero\footnote{
150    In fact it is assumed they are not present by assigning the value \code{escript.Data()}. The
151    can by used by the solver library to reduce computational costs.
152    }
153  If the new coefficient value is not a \Data object, it is converted into a \Data object in the  If the new coefficient value is not a \Data object, it is converted into a \Data object in the
154  appropriate \FunctionSpace.  appropriate \FunctionSpace.
155  \end{methoddesc}  \end{methoddesc}
156    
157  \begin{methoddesc}[LinearPDE]{getCoefficient}{name}  \begin{methoddesc}[LinearPDE]{getCoefficient}{name}
158  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
159  an exception is raised.  an exception is raised.
160  \end{methoddesc}  \end{methoddesc}
161    
162  \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}  \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
# Line 162  switches the debug mode to on. Line 176  switches the debug mode to on.
176  \end{methoddesc}  \end{methoddesc}
177    
178  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
179  returns \True if lumping is switched on. Otherwise \False is returned.  returns \True if \LUMPING is set as the solver for the system of linear equations.
180    Otherwise \False is returned.
181  \end{methoddesc}  \end{methoddesc}
182    
183  \begin{methoddesc}[LinearPDE]{setSolverMethod}{\optional{solver=LinearPDE.DEFAULT}\options{, preconditioner=LinearPDE.DEFAULT})  \begin{methoddesc}[LinearPDE]{setSolverMethod}{\optional{solver=LinearPDE.DEFAULT}\optional{, preconditioner=LinearPDE.DEFAULT}}
184  sets the solver method and preconditioner to be used. It is pointed out that a PDE solver library  sets the solver method and preconditioner to be used. It is pointed out that a PDE solver library
185  may not know the specified solver method but may choose a similar method and preconditioner.  may not know the specified solver method but may choose a similar method and preconditioner.
186  \end{methoddesc}  \end{methoddesc}
187    
188    \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}
189    returns the name of the solver method and preconditioner which is currently been used.
190    \end{methoddesc}
191    
192    \begin{methoddesc}[LinearPDE]{getSolverMethod}{}
193    returns the solver method and preconditioner which is currently been used.
194    \end{methoddesc}
195    
196    \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=LinearPDE.DEFAULT}}
197    Set the solver package to be used by PDE library to solve the linear systems of equations. The
198    specified package may not be supported by the PDE solver library. In this case, depending on
199    the PDE solver, the default solver is used or an exception is thrown.
200    If \var{package} is not specified, the default package of the PDE solver library is used.
201    \end{methoddesc}
202    
203    \begin{methoddesc}[LinearPDE]{getSolverPackage}{}
204    returns the linear solver package currently by the PDE solver library
205    \end{methoddesc}
206    
207    
208  \begin{methoddesc}[LinearPDE]{setTolerance}{\optional{tol=1.e-8}}:  \begin{methoddesc}[LinearPDE]{setTolerance}{\optional{tol=1.e-8}}:
209  resets the tolerance for solution. The actually meaning of tolerance is  resets the tolerance for solution. The actually meaning of tolerance is
210  depending on the underlying PDE library. In most cases, the tolerance  depending on the underlying PDE library. In most cases, the tolerance
211  will only consider the error from solving the discerete problem but will  will only consider the error from solving the discrete problem but will
212  not consider any discretization error.  not consider any discretization error.
213  \end{methoddesc}  \end{methoddesc}
214    
215    \begin{methoddesc}[LinearPDE]{setToleranceReductionFactor}{TOL}
216    Lowers the tolerance by a factor of TOL.
217    \end{methoddesc}
218    
219  \begin{methoddesc}[LinearPDE]{getTolerance}{}  \begin{methoddesc}[LinearPDE]{getTolerance}{}
220  returns the current tolerance of the solution  returns the current tolerance of the solution
221  \end{methoddesc}  \end{methoddesc}
# Line 198  returns the number of components of the Line 237  returns the number of components of the
237  \end{methoddesc}  \end{methoddesc}
238    
239  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
240  returns \True if the PDE is symmetric and \False otherwise.  returns \True if the PDE is symmetric and \False otherwise.
241  The method is very computational expensive and should only be  The method is very computational expensive and should only be
242  called for testing purposes. The symmetry flag is not altered.  called for testing purposes. The symmetry flag is not altered.
243  If \var{verbose}=\True information about where symmetry is violated  If \var{verbose}=\True information about where symmetry is violated
244  are printed.  are printed.
# Line 210  returns the flux $J\hackscore{ij}$ \inde Line 249  returns the flux $J\hackscore{ij}$ \inde
249  defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.  defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
250  \end{methoddesc}  \end{methoddesc}
251    
 \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}  
 \begin{methoddesc}[LinearPDE]{getSolverMethod}{}  
 \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=None}}  
 \begin{methoddesc}[LinearPDE]{getSolverPackage}{}  
252    
253  \begin{methoddesc}[LinearPDE]{isSymmetric}{}  \begin{methoddesc}[LinearPDE]{isSymmetric}{}
254  returns \True if the PDE has been indicated to be symmetric.  returns \True if the PDE has been indicated to be symmetric.
# Line 229  indicates that the PDE is not symmetric. Line 264  indicates that the PDE is not symmetric.
264  \end{methoddesc}  \end{methoddesc}
265    
266  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
267  switches on the reduction of polynomial order for the solution and equation evaluation even if  switches on the reduction of polynomial order for the solution and equation evaluation even if
268  a quadratic or higher interpolation order is defined in the \Domain. This feature may not  a quadratic or higher interpolation order is defined in the \Domain. This feature may not
269  be supported by all PDE libraries.  be supported by all PDE libraries.
270  \end{methoddesc}  \end{methoddesc}
271    
272  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
273  switches off the reduction of polynomial order for the solution and  switches off the reduction of polynomial order for the solution and
274  equation evaluation.  equation evaluation.
275  \end{methoddesc}  \end{methoddesc}
276    
# Line 262  returns the \Operator and right hand sid Line 297  returns the \Operator and right hand sid
297  \optional{, truncation=-1}  \optional{, truncation=-1}
298  \optional{, restart=-1}  \optional{, restart=-1}
299  }  }
300  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.  returns (an approximation of) the solution of the PDE. If \code{verbose=\True} some information during the solution process printed.
301  \var{iter_max} specifies the maximum number of iteration steps that are allowed to reach the specified tolerence.  \var{reordering} selects a reordering methods that is applied before or during the solution process
302    (=\NOREORDERING ,\MINIMUMFILLIN ,\NESTEDDESCTION).
303    \var{iter_max} specifies the maximum number of iteration steps that are allowed to reach the specified tolerance.
304  \var{drop_tolerance} specifies a relative tolerance for small elements to be dropped when building a preconditioner  \var{drop_tolerance} specifies a relative tolerance for small elements to be dropped when building a preconditioner
305  (eg. in ILUT \Ref{SAAD}). \var{drop_storage} limits the extra storage allowed when building a preconditioner  (eg. in \ILUT). \var{drop_storage} limits the extra storage allowed when building a preconditioner
306  (eg. in ILUT \Ref{SAAD}). The extra storage is given relative to the size of the siffness matrix, eg.  (eg. in \ILUT). The extra storage is given relative to the size of the stiffness matrix, eg.
307  \var{drop_storage=1.2} will allow the preconditioner to use the $1.2$ fold storage space than used  \var{drop_storage=1.2} will allow the preconditioner to use the $1.2$ fold storage space than used
308  for the stiffness matrix. \var{truncation} defines the truncation  for the stiffness matrix. \var{truncation} defines the truncation.
309  \end{methoddesc}  \end{methoddesc}
310    
 ==================  
311  \begin{memberdesc}[LinearPDE]{DEFAULT}  \begin{memberdesc}[LinearPDE]{DEFAULT}
312  default method, preconditioner or package to be used to solve the PDE. An appropriate method should be  default method, preconditioner or package to be used to solve the PDE. An appropriate method should be
313  chosen by the used PDE solver library.  chosen by the used PDE solver library.
314  \end{memberdesc}  \end{memberdesc}
315    
316  \begin{memberdesc}[LinearPDE]{SCSL}  \begin{memberdesc}[LinearPDE]{SCSL}
317    the SCSL library by SGI,~\Ref{SCSL}\footnote{The SCSL library will only be available on SGI systems}
318  \end{memberdesc}  \end{memberdesc}
319    
320  \begin{memberdesc}[LinearPDE]{MKL}  \begin{memberdesc}[LinearPDE]{MKL}
321    the MKL library by Intel,~\Ref{MKL}\footnote{The MKL library will only be available when the Intel compilation environment is used.}.
322  \end{memberdesc}  \end{memberdesc}
323    
324  \begin{memberdesc}[LinearPDE]{UMFPACK}  \begin{memberdesc}[LinearPDE]{UMFPACK}
325    the UMFPACK,~\Ref{UMFPACK}. Remark: UMFPACK is not parallelized.
326  \end{memberdesc}  \end{memberdesc}
327    
328  \begin{memberdesc}[LinearPDE]{PASO}  \begin{memberdesc}[LinearPDE]{PASO}
329    the solver library of \finley, see \Sec{CHAPTER ON FINLEY}.
330  \end{memberdesc}  \end{memberdesc}
331    
332  \begin{memberdesc}[LinearPDE]{ITERATIVE}  \begin{memberdesc}[LinearPDE]{ITERATIVE}
333    the default iterative method and preconditioner. The actually used method depends on the
334    PDE solver library and the solver package been chosen. Typically, \PCG is used for symmetric PDEs
335    and \BiCGStab otherwise, both with \JACOBI preconditioner.
336  \end{memberdesc}  \end{memberdesc}
337    
338  \begin{memberdesc}[LinearPDE]{DIRECT}  \begin{memberdesc}[LinearPDE]{DIRECT}
339  direct linear solver~\Ref{SAAD}  the default direct linear solver.
340  \end{memberdesc}  \end{memberdesc}
341    
342  \begin{memberdesc}[LinearPDE]{CHOLEVSKY}  \begin{memberdesc}[LinearPDE]{CHOLEVSKY}
343  direct solver based on Cholevsky factorization (or similar), see~\Ref{SAAD}. The solver will require a symmetric PDE.  direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE.
344  \end{memberdesc}  \end{memberdesc}
345    
346  \begin{memberdesc}[LinearPDE]{PCG}  \begin{memberdesc}[LinearPDE]{PCG}
347  preconditioned conjugate gradient method, see~\Ref{WEISS}. The solver will require a symmetric PDE.  preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE.
348  \end{memberdesc}  \end{memberdesc}
349    
350  \begin{memberdesc}[LinearPDE]{GMRES}  \begin{memberdesc}[LinearPDE]{GMRES}
351  the GMRES method, see~\Ref{WEISS}. Truncation and restart ar econtrolled by the parameters  the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters
352  \var{truncation} and \var{restart} of \method{getSolution}.  \var{truncation} and \var{restart} of \method{getSolution}.
353  \end{memberdesc}  \end{memberdesc}
354    
355  \begin{memberdesc}[LinearPDE]{LUMPING}  \begin{memberdesc}[LinearPDE]{LUMPING}
356  conjugate residual method, see~\Ref{WEISS}.  uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
357    condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
358    only \var{D} is present but in any case has to applied with care. The difference in the solutions with and without lumping can be significant
359    but is expect to converge to zero when the mesh gets finer.
360    Lumping does not use the linear system solver library.
361  \end{memberdesc}  \end{memberdesc}
362    
363  \begin{memberdesc}[LinearPDE]{PRES20}  \begin{memberdesc}[LinearPDE]{PRES20}
364  the GMRES method with trunction after five residuals and  the GMRES method with truncation after five residuals and
365  restart after 20 steps, see~\Ref{WEISS}.  restart after 20 steps, see~\Ref{WEISS}.
366    \end{memberdesc}
 \begin{memberdesc}[LinearPDE]{CR}  
367    
368  \begin{memberdesc}[LinearPDE]{CGS}  \begin{memberdesc}[LinearPDE]{CGS}
369  conjugate gradient squared method, see~\Ref{WEISS}.  conjugate gradient squared method, see~\Ref{WEISS}.
370  \end{memberdesc}  \end{memberdesc}
371    
372  \begin{memberdesc}[LinearPDE]{BICGSTAB}  \begin{memberdesc}[LinearPDE]{BICGSTAB}
373  stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.  stabilized bi-conjugate gradients methods, see~\Ref{WEISS}.
374  \end{memberdesc}  \end{memberdesc}
375    
376  \begin{memberdesc}[LinearPDE]{SSOR}  \begin{memberdesc}[LinearPDE]{SSOR}
377  symmetric successive overrelaxtion method, see~\Ref{WEISS}.  symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support
378    this as a solver.
379  \end{memberdesc}  \end{memberdesc}
380  \begin{memberdesc}[LinearPDE]{ILU0}  \begin{memberdesc}[LinearPDE]{ILU0}
381    the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}.
382    \end{memberdesc}
383    
384  \begin{memberdesc}[LinearPDE]{ILUT}  \begin{memberdesc}[LinearPDE]{ILUT}
385  \begin{memberdesc}[LinearPDE]{JACOBI}  the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the  LU-factorization element with
386  \begin{memberdesc}[LinearPDE]{AMG}  relative size less then \var{drop_tolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
387  \begin{memberdesc}[LinearPDE]{RILU}  \var{drop_storage}-fold of the stiffness matrix. \var{drop_tolerance} and \var{drop_storage} are both set in the
388    \method{getSolution} call.
389    \end{memberdesc}
390    
391    \begin{memberdesc}[LinearPDE]{JACOBI}
392    the Jacobi preconditioner, see~\Ref{Saad}.
393    \end{memberdesc}
394    
395    \begin{memberdesc}[LinearPDE]{AMG}
396    the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used
397    in a preconditioner.
398    \end{memberdesc}
399    
400    \begin{memberdesc}[LinearPDE]{RILU}
401    recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILUT but uses smoothing
402    between levels. During the  LU-factorization element with
403    relative size less then \var{drop_tolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
404    \var{drop_storage}-fold of the stiffness matrix. \var{drop_tolerance} and \var{drop_storage} are both set in the
405    \method{getSolution} call.
406    \end{memberdesc}
407    
408  \begin{memberdesc}[LinearPDE]{NO_REORDERING}  \begin{memberdesc}[LinearPDE]{NO_REORDERING}
409  \begin{memberdesc}[LinearPDE]{MINIMUM_FILL_IN}  no ordering is used during factorization.
410  \begin{memberdesc}[LinearPDE]{NESTED_DISSECTION}  \end{memberdesc}
   
   
   
411    
412  \begin{memberdesc}[LinearPDE]{BICGSTAB}  \begin{memberdesc}[LinearPDE]{MINIMUM_FILL_IN}
413    applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or
414    linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
415    \end{memberdesc}
416    
417    \begin{memberdesc}[LinearPDE]{NESTED_DISSECTION}
418    applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or
419    linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
420    \end{memberdesc}
421    
422  \section{The \Poisson Class}  \subsection{The \Poisson Class}
423  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
424  equation  equation
425  \begin{equation}\label{POISSON.1}  \begin{equation}\label{POISSON.1}
# Line 365  and homogeneous constraints Line 434  and homogeneous constraints
434  u=0 \mbox{ where } q>0  u=0 \mbox{ where } q>0
435  \end{equation}  \end{equation}
436  $f$ has to be a \Scalar in the \Function and $q$ must be  $f$ has to be a \Scalar in the \Function and $q$ must be
437  a \Scalar in  the \SolutionFS.  a \Scalar in  the \SolutionFS.
438    
439  \begin{classdesc}{Poisson}{domain}  \begin{classdesc}{Poisson}{domain}
440  opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.  opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
# Line 374  opens a Poisson equation on the \Domain Line 443  opens a Poisson equation on the \Domain
443  assigns new values to \var{f} and \var{q}.  assigns new values to \var{f} and \var{q}.
444  \end{methoddesc}  \end{methoddesc}
445    
446  \section{The \Helmholtz Class}  \subsection{The \Helmholtz Class}
447    The \Helmholtz class defines the Helmholtz problem
448    \begin{equation}\label{HZ.1}
449    \omega \; u - (k\; u\hackscore{,j})\hackscore{,j} = f
450    \end{equation}
451     with natural boundary conditions
452    \begin{equation}\label{HZ.2}
453    k\; u\hackscore{,j} n\hackscore{,j} = g- \alpha \; u
454    \end{equation}
455    and constraints:
456    \begin{equation}\label{HZ.3}
457    u=r \mbox{ where } q>0
458    \end{equation}
459    $\omega$, $k$, $f$ have to be a \Scalar in the \Function,
460    $g$ and $\alpha$ must be a \Scalar in  the \FunctionOnBoundary,
461    and $q$ and $r$ must be a \Scalar in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
462    
463    \begin{classdesc}{Helmholtz}{domain}
464    opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE.
465    \end{classdesc}
466    \begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}}
467    assigns new values to \var{omega}, \var{k}, \var{f}, \var{alpha}, \var{g}, \var{r}, \var{q}. By default all values are set to be zero.
468    \end{methoddesc}
469    
470    \subsection{The \Lame Class}
471    The \Lame class defines a Lame equation problem:
472    \begin{equation}\label{LE.1}
473    -\mu (u\hackscore{i,j}+u\hackscore{j,i})+\lambda u\hackscore{k,k})\hackscore{j} = F\hackscore{i}-\sigma\hackscore{ij,j}
474    \end{equation}
475    with natural boundary conditions:
476    \begin{equation}\label{LE.2}
477    n\hackscore{j}(\mu \; (u\hackscore{i,j}+u\hackscore{j,i})+\lambda*u\hackscore{k,k}) = f\hackscore{i}+n\hackscore{j}\sigma\hackscore{ij}
478    \end{equation}
479    and constraint
480    \begin{equation}\label{LE.3}
481    u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
482    \end{equation}
483    $\mu$, $\lambda$ have to be a \Scalar in the \Function,
484    $F$ has to be a \Vector in the \Function,
485    $\sigma$ has to be a \Tensor in the \Function,
486    $f$ must be a \Vector in  the \FunctionOnBoundary,
487    and $q$ and $r$ must be a \Vector in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
488    
489  \section{The \Lame Class}  \begin{classdesc}{Lame}{domain}
490    opens a Lame equation on the \Domain domain. \Lame is derived from \LinearPDE.
491    \end{classdesc}
492    \begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}}
493    assigns new values to
494    \var{lame_lambda},
495    \var{lame_mu},
496    \var{F},
497    \var{sigma},
498    \var{f},
499    \var{r} and
500    \var{q}
501    By default all values are set to be zero.
502    \end{methoddesc}
503    

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

  ViewVC Help
Powered by ViewVC 1.1.26