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

trunk/doc/user/linearPDE.tex revision 625 by gross, Thu Mar 23 00:41:25 2006 UTC temp_trunk_copy/doc/user/linearPDE.tex revision 1384 by phornby, Fri Jan 11 02:29:38 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    
# Line 198  returns the number of components of the Line 233  returns the number of components of the
233  \end{methoddesc}  \end{methoddesc}
234    
235  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}  \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
236  returns \True if the PDE is symmetric and \False otherwise.  returns \True if the PDE is symmetric and \False otherwise.
237  The method is very computational expensive and should only be  The method is very computational expensive and should only be
238  called for testing purposes. The symmetry flag is not altered.  called for testing purposes. The symmetry flag is not altered.
239  If \var{verbose}=\True information about where symmetry is violated  If \var{verbose}=\True information about where symmetry is violated
240  are printed.  are printed.
# Line 210  returns the flux $J\hackscore{ij}$ \inde Line 245  returns the flux $J\hackscore{ij}$ \inde
245  defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.  defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
246  \end{methoddesc}  \end{methoddesc}
247    
 \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}  
 \begin{methoddesc}[LinearPDE]{getSolverMethod}{}  
 \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=None}}  
 \begin{methoddesc}[LinearPDE]{getSolverPackage}{}  
248    
249  \begin{methoddesc}[LinearPDE]{isSymmetric}{}  \begin{methoddesc}[LinearPDE]{isSymmetric}{}
250  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 260  indicates that the PDE is not symmetric.
260  \end{methoddesc}  \end{methoddesc}
261    
262  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}  \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
263  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
264  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
265  be supported by all PDE libraries.  be supported by all PDE libraries.
266  \end{methoddesc}  \end{methoddesc}
267    
268  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}  \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
269  switches off the reduction of polynomial order for the solution and  switches off the reduction of polynomial order for the solution and
270  equation evaluation.  equation evaluation.
271  \end{methoddesc}  \end{methoddesc}
272    
# Line 262  returns the \Operator and right hand sid Line 293  returns the \Operator and right hand sid
293  \optional{, truncation=-1}  \optional{, truncation=-1}
294  \optional{, restart=-1}  \optional{, restart=-1}
295  }  }
296  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.
297  \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
298    (=\NOREORDERING ,\MINIMUMFILLIN ,\NESTEDDESCTION).
299    \var{iter_max} specifies the maximum number of iteration steps that are allowed to reach the specified tolerance.
300  \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
301  (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
302  (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.
303  \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
304  for the stiffness matrix. \var{truncation} defines the truncation  for the stiffness matrix. \var{truncation} defines the truncation.
305  \end{methoddesc}  \end{methoddesc}
306    
 ==================  
307  \begin{memberdesc}[LinearPDE]{DEFAULT}  \begin{memberdesc}[LinearPDE]{DEFAULT}
308  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
309  chosen by the used PDE solver library.  chosen by the used PDE solver library.
310  \end{memberdesc}  \end{memberdesc}
311    
312  \begin{memberdesc}[LinearPDE]{SCSL}  \begin{memberdesc}[LinearPDE]{SCSL}
313    the SCSL library by SGI,~\Ref{SCSL}\footnote{The SCSL library will only be available on SGI systems}
314  \end{memberdesc}  \end{memberdesc}
315    
316  \begin{memberdesc}[LinearPDE]{MKL}  \begin{memberdesc}[LinearPDE]{MKL}
317    the MKL library by Intel,~\Ref{MKL}\footnote{The MKL library will only be available when the intel compilation environment is used.}.
318  \end{memberdesc}  \end{memberdesc}
319    
320  \begin{memberdesc}[LinearPDE]{UMFPACK}  \begin{memberdesc}[LinearPDE]{UMFPACK}
321    the UMFPACK,~\Ref{UMFPACK}. Remark: UMFPACK is not parallelized.
322  \end{memberdesc}  \end{memberdesc}
323    
324  \begin{memberdesc}[LinearPDE]{PASO}  \begin{memberdesc}[LinearPDE]{PASO}
325    the solver library of \finley, see \Sec{CHAPTER ON FINLEY}.
326  \end{memberdesc}  \end{memberdesc}
327    
328  \begin{memberdesc}[LinearPDE]{ITERATIVE}  \begin{memberdesc}[LinearPDE]{ITERATIVE}
329    the default iterative method and preconditioner. The actually used method depends on the
330    PDE solver library and the solver package been chosen. Typically, \PCG is used for symmetric PDEs
331    and \BiCGStab otherwise, both with \JACOBI preconditioner.
332  \end{memberdesc}  \end{memberdesc}
333    
334  \begin{memberdesc}[LinearPDE]{DIRECT}  \begin{memberdesc}[LinearPDE]{DIRECT}
335  direct linear solver~\Ref{SAAD}  the default direct linear solver.
336  \end{memberdesc}  \end{memberdesc}
337    
338  \begin{memberdesc}[LinearPDE]{CHOLEVSKY}  \begin{memberdesc}[LinearPDE]{CHOLEVSKY}
339  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.
340  \end{memberdesc}  \end{memberdesc}
341    
342  \begin{memberdesc}[LinearPDE]{PCG}  \begin{memberdesc}[LinearPDE]{PCG}
343  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.
344  \end{memberdesc}  \end{memberdesc}
345    
346  \begin{memberdesc}[LinearPDE]{GMRES}  \begin{memberdesc}[LinearPDE]{GMRES}
347  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
348  \var{truncation} and \var{restart} of \method{getSolution}.  \var{truncation} and \var{restart} of \method{getSolution}.
349  \end{memberdesc}  \end{memberdesc}
350    
351  \begin{memberdesc}[LinearPDE]{LUMPING}  \begin{memberdesc}[LinearPDE]{LUMPING}
352  conjugate residual method, see~\Ref{WEISS}.  uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
353    condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
354    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
355    but is expect to converge to zero when the mesh gets finer.
356    Lumping does not use the linear system solver library.
357  \end{memberdesc}  \end{memberdesc}
358    
359  \begin{memberdesc}[LinearPDE]{PRES20}  \begin{memberdesc}[LinearPDE]{PRES20}
360  the GMRES method with trunction after five residuals and  the GMRES method with truncation after five residuals and
361  restart after 20 steps, see~\Ref{WEISS}.  restart after 20 steps, see~\Ref{WEISS}.
362    \end{memberdesc}
 \begin{memberdesc}[LinearPDE]{CR}  
363    
364  \begin{memberdesc}[LinearPDE]{CGS}  \begin{memberdesc}[LinearPDE]{CGS}
365  conjugate gradient squared method, see~\Ref{WEISS}.  conjugate gradient squared method, see~\Ref{WEISS}.
366  \end{memberdesc}  \end{memberdesc}
367    
368  \begin{memberdesc}[LinearPDE]{BICGSTAB}  \begin{memberdesc}[LinearPDE]{BICGSTAB}
369  stabilzed bi-conjugate gradients methods, see~\Ref{WEISS}.  stabilized bi-conjugate gradients methods, see~\Ref{WEISS}.
370  \end{memberdesc}  \end{memberdesc}
371    
372  \begin{memberdesc}[LinearPDE]{SSOR}  \begin{memberdesc}[LinearPDE]{SSOR}
373  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
374    this as a solver.
375  \end{memberdesc}  \end{memberdesc}
376  \begin{memberdesc}[LinearPDE]{ILU0}  \begin{memberdesc}[LinearPDE]{ILU0}
377    the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}.
378    \end{memberdesc}
379    
380  \begin{memberdesc}[LinearPDE]{ILUT}  \begin{memberdesc}[LinearPDE]{ILUT}
381  \begin{memberdesc}[LinearPDE]{JACOBI}  the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the  LU-factorization element with
382  \begin{memberdesc}[LinearPDE]{AMG}  relative size less then \var{drop_tolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
383  \begin{memberdesc}[LinearPDE]{RILU}  \var{drop_storage}-fold of the stiffness matrix. \var{drop_tolerance} and \var{drop_storage} are both set in the
384    \method{getSolution} call.
385    \end{memberdesc}
386    
387    \begin{memberdesc}[LinearPDE]{JACOBI}
388    the Jacobi preconditioner, see~\Ref{Saad}.
389    \end{memberdesc}
390    
391    \begin{memberdesc}[LinearPDE]{AMG}
392    the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used
393    in a preconditioner.
394    \end{memberdesc}
395    
396    \begin{memberdesc}[LinearPDE]{RILU}
397    recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILUT but uses smoothing
398    between levels. During the  LU-factorization element with
399    relative size less then \var{drop_tolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
400    \var{drop_storage}-fold of the stiffness matrix. \var{drop_tolerance} and \var{drop_storage} are both set in the
401    \method{getSolution} call.
402    \end{memberdesc}
403    
404  \begin{memberdesc}[LinearPDE]{NO_REORDERING}  \begin{memberdesc}[LinearPDE]{NO_REORDERING}
405  \begin{memberdesc}[LinearPDE]{MINIMUM_FILL_IN}  no ordering is used during factorization.
406  \begin{memberdesc}[LinearPDE]{NESTED_DISSECTION}  \end{memberdesc}
   
   
   
407    
408  \begin{memberdesc}[LinearPDE]{BICGSTAB}  \begin{memberdesc}[LinearPDE]{MINIMUM_FILL_IN}
409    applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or
410    linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
411    \end{memberdesc}
412    
413    \begin{memberdesc}[LinearPDE]{NESTED_DISSECTION}
414    applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or
415    linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
416    \end{memberdesc}
417    
418  \section{The \Poisson Class}  \subsection{The \Poisson Class}
419  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
420  equation  equation
421  \begin{equation}\label{POISSON.1}  \begin{equation}\label{POISSON.1}
# Line 365  and homogeneous constraints Line 430  and homogeneous constraints
430  u=0 \mbox{ where } q>0  u=0 \mbox{ where } q>0
431  \end{equation}  \end{equation}
432  $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
433  a \Scalar in  the \SolutionFS.  a \Scalar in  the \SolutionFS.
434    
435  \begin{classdesc}{Poisson}{domain}  \begin{classdesc}{Poisson}{domain}
436  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 439  opens a Poisson equation on the \Domain
439  assigns new values to \var{f} and \var{q}.  assigns new values to \var{f} and \var{q}.
440  \end{methoddesc}  \end{methoddesc}
441    
442  \section{The \Helmholtz Class}  \subsection{The \Helmholtz Class}
443    The \Helmholtz class defines the Helmholtz problem
444    \begin{equation}\label{HZ.1}
445    \omega \; u - (k\; u\hackscore{,j})\hackscore{,j} = f
446    \end{equation}
447     with natural boundary conditions
448    \begin{equation}\label{HZ.2}
449    k\; u\hackscore{,j} n\hackscore{,j} = g- \alpha \; u
450    \end{equation}
451    and constraints:
452    \begin{equation}\label{HZ.3}
453    u=r \mbox{ where } q>0
454    \end{equation}
455    $\omega$, $k$, $f$ have to be a \Scalar in the \Function,
456    $g$ and $\alpha$ must be a \Scalar in  the \FunctionOnBoundary,
457    and $q$ and $r$ must be a \Scalar in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
458    
459    \begin{classdesc}{Helmholtz}{domain}
460    opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE.
461    \end{classdesc}
462    \begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}}
463    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.
464    \end{methoddesc}
465    
466    \subsection{The \Lame Class}
467    The \Lame class defines a Lame equation problem:
468    \begin{equation}\label{LE.1}
469    -\mu (u\hackscore{i,j}+u\hackscore{j,i})+\lambda u\hackscore{k,k})\hackscore{j} = F\hackscore{i}-\sigma\hackscore{ij,j}
470    \end{equation}
471    with natural boundary conditions:
472    \begin{equation}\label{LE.2}
473    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}
474    \end{equation}
475    and constraint
476    \begin{equation}\label{LE.3}
477    u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
478    \end{equation}
479    $\mu$, $\lambda$ have to be a \Scalar in the \Function,
480    $F$ has to be a \Vector in the \Function,
481    $\sigma$ has to be a \Tensor in the \Function,
482    $f$ must be a \Vector in  the \FunctionOnBoundary,
483    and $q$ and $r$ must be a \Vector in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.
484    
485  \section{The \Lame Class}  \begin{classdesc}{Lame}{domain}
486    opens a Lame equation on the \Domain domain. \Lame is derived from \LinearPDE.
487    \end{classdesc}
488    \begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}}
489    assigns new values to
490    \var{lame_lambda},
491    \var{lame_mu},
492    \var{F},
493    \var{sigma},
494    \var{f},
495    \var{r} and
496    \var{q}
497    By default all values are set to be zero.
498    \end{methoddesc}
499    

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

  ViewVC Help
Powered by ViewVC 1.1.26