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

revision 1958 by ksteube, Thu Sep 25 23:11:13 2008 UTC revision 1959 by jfenwick, Tue Nov 4 01:49:19 2008 UTC
# Line 102  A\hackscore{jl}=A\hackscore{lj} \mbox{ a Line 102  A\hackscore{jl}=A\hackscore{lj} \mbox{ a
102  The system of PDEs is symmetrical \index{symmetrical} if  The system of PDEs is symmetrical \index{symmetrical} if
103  \begin{eqnarray}  \begin{eqnarray}
104  \label{LINEARPDE.SYSTEM.4}  \label{LINEARPDE.SYSTEM.4}
105  A\hackscore{ijkl}=A\hackscore{klij} \\  A\hackscore{ijkl}&=&A\hackscore{klij} \\
106  B\hackscore{ijk}=C\hackscore{kij} \\  B\hackscore{ijk}&=&C\hackscore{kij} \\
107  D\hackscore{ik}=D\hackscore{ki} \\  D\hackscore{ik}&=&D\hackscore{ki} \\
108  d\hackscore{ik}=d\hackscore{ki} \\  d\hackscore{ik}&=&d\hackscore{ki} \\
109  d^{contact}\hackscore{ik}=d^{contact}\hackscore{ki}  d^{contact}\hackscore{ik}&=&d^{contact}\hackscore{ki}
110  \end{eqnarray}  \end{eqnarray}
111  Note that different from the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$  Note that in contrast with the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$
112  have to be inspected.  have to be inspected.
113
114
# Line 116  have to be inspected. Line 116  have to be inspected.
116  \declaremodule{extension}{esys.escript.linearPDEs}  \declaremodule{extension}{esys.escript.linearPDEs}
117  \modulesynopsis{Linear partial differential equation handler}  \modulesynopsis{Linear partial differential equation handler}
118  The module \linearPDEs provides an interface to define and solve linear partial  The module \linearPDEs provides an interface to define and solve linear partial
119  differential equations within \escript. \linearPDEs does not provide any  differential equations within \escript. The module \linearPDEs does not provide any
120  solver capabilities in itself but hands the PDE over to  solver capabilities in itself but hands the PDE over to
121  the PDE solver library defined through the \Domain of the PDE.  the PDE solver library defined through the \Domain of the PDE.
122  The general interface is provided through the \LinearPDE class. The  The general interface is provided through the \LinearPDE class. The
123  \AdvectivePDE which is derived from the \LinearPDE class  \AdvectivePDE which is derived from the \LinearPDE class
124  provides an interface to PDE dominated by its advective terms. The \Poisson  provides an interface to a PDE dominated by its advective terms. The \Poisson
125  class which is also derived form the \LinearPDE class should be used  class which is also derived form the \LinearPDE class should be used
126  to define the Poisson equation \index{Poisson}.  to define the Poisson equation \index{Poisson}.
127
128  \subsection{\LinearPDE class}  \subsection{\LinearPDE class}
129  This is the general class to define a linear PDE in \escript. We list a selection of the most  This is the general class to define a linear PDE in \escript. We list a selection of the most
130  important methods of the class only and refer to reference guide \ReferenceGuide for a complete list.  important methods of the class. For a complete list, see the reference at \ReferenceGuide.
131
132  \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}  \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
133  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}
# Line 137  and the number solutions, respectively, Line 137  and the number solutions, respectively,
137  defined.  defined.
138  \end{classdesc}  \end{classdesc}
139
140    \subsubsection{\LinearPDE methods}
141
142  \begin{methoddesc}[LinearPDE]{setValue}{  \begin{methoddesc}[LinearPDE]{setValue}{
143  \optional{A}\optional{, B},  \optional{A}\optional{, B},
144  \optional{, C}\optional{, D}  \optional{, C}\optional{, D}
# Line 166  returns the \FunctionSpace of coefficien Line 168  returns the \FunctionSpace of coefficien
168  \end{methoddesc}  \end{methoddesc}
169
170  \begin{methoddesc}[LinearPDE]{setDebugOn}{}  \begin{methoddesc}[LinearPDE]{setDebugOn}{}
171  switches the debug mode to on.  switches on debug mode.
172  \end{methoddesc}  \end{methoddesc}
173
174  \begin{methoddesc}[LinearPDE]{setDebugOff}{}  \begin{methoddesc}[LinearPDE]{setDebugOff}{}
175  switches the debug mode to on.  switches off debug mode.
176  \end{methoddesc}  \end{methoddesc}
177
178  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}  \begin{methoddesc}[LinearPDE]{isUsingLumping}{}
# Line 179  Otherwise \False is returned. Line 181  Otherwise \False is returned.
181  \end{methoddesc}  \end{methoddesc}
182
183  \begin{methoddesc}[LinearPDE]{setSolverMethod}{\optional{solver=LinearPDE.DEFAULT}\optional{, 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 should be noted 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}{}  \begin{methoddesc}[LinearPDE]{getSolverMethodName}{}
189  returns the name of the solver method and preconditioner which is currently been used.  returns the name of the solver method and preconditioner which is in use.
190  \end{methoddesc}  \end{methoddesc}
191
192  \begin{methoddesc}[LinearPDE]{getSolverMethod}{}  \begin{methoddesc}[LinearPDE]{getSolverMethod}{}
193  returns the solver method and preconditioner which is currently been used.  returns the solver method and preconditioner which is in use.
194  \end{methoddesc}  \end{methoddesc}
195
196  \begin{methoddesc}[LinearPDE]{setSolverPackage}{\optional{package=LinearPDE.DEFAULT}}  \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  sets 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  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.  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.  If \var{package} is not specified, the default package of the PDE solver library is used.
# Line 203  returns the linear solver package curren Line 205  returns the linear solver package curren
205  \end{methoddesc}  \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 depends
210  depending on the underlying PDE library. In most cases, the tolerance  on the underlying PDE library. In most cases, the tolerance
211  will only consider the error from solving the discrete 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}  \begin{methoddesc}[LinearPDE]{setToleranceReductionFactor}{TOL}
216  Lowers the tolerance by a factor of TOL.  lowers the tolerance by a factor of TOL.
217  \end{methoddesc}  \end{methoddesc}
218
219  \begin{methoddesc}[LinearPDE]{getTolerance}{}  \begin{methoddesc}[LinearPDE]{getTolerance}{}
# Line 236  returns the number of components of the Line 238  returns the number of components of the
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 computationally 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 278  returns the \Operator of the PDE. Line 280  returns the \Operator of the PDE.
280
281  \begin{methoddesc}[LinearPDE]{getRightHandSide}{}  \begin{methoddesc}[LinearPDE]{getRightHandSide}{}
282  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
283  \var{ignoreConstraint}=\True the constraints are not considered  \var{ignoreConstraint}=\True, then the constraints are not considered
284  when building up the right hand side.  when building up the right hand side.
285  \end{methoddesc}  \end{methoddesc}
286
# Line 295  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 printed.  returns (an approximation of) the solution of the PDE. If \code{verbose=\True}, then some information is printed during the solution process.
301  \var{reordering} selects a reordering methods that is applied before or during the solution process  \var{reordering} selects a reordering methods that is applied before or during the solution process
302  (=\NOREORDERING ,\MINIMUMFILLIN ,\NESTEDDESCTION).  (=\NOREORDERING, \MINIMUMFILLIN, \NESTEDDESCTION).
303  \var{iter_max} specifies the maximum number of iteration steps that are allowed to reach the specified tolerance.  \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). \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
# Line 306  returns (an approximation of) the soluti Line 308  returns (an approximation of) the soluti
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    \subsubsection{\LinearPDE symbols/members}
312
313  \begin{memberdesc}[LinearPDE]{DEFAULT}  \begin{memberdesc}[LinearPDE]{DEFAULT}
314  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
315  chosen by the used PDE solver library.  chosen by the used PDE solver library.
# Line 354  the GMRES method, see~\Ref{WEISS}\index{ Line 358  the GMRES method, see~\Ref{WEISS}\index{
358  uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique  uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
359  condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when  condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
360  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  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
361  but is expect to converge to zero when the mesh gets finer.  but is expected to converge to zero when the mesh gets finer.
362  Lumping does not use the linear system solver library.  Lumping does not use the linear system solver library.
363  \end{memberdesc}  \end{memberdesc}
364

Legend:
 Removed from v.1958 changed lines Added in v.1959