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

Revision 2559 - (show annotations)
Mon Jul 27 05:19:21 2009 UTC (10 years, 2 months ago) by artak
File MIME type: application/x-tex
File size: 37682 byte(s)
typo: MaxIter changed IterMax

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % 4 % Copyright (c) 2003-2009 by University of Queensland 5 % Earth Systems Science Computational Center (ESSCC) 6 7 % 8 % Primary Business: Queensland, Australia 9 % Licensed under the Open Software License version 3.0 10 11 % 12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 13 14 15 \chapter{The Module \linearPDEs} 16 17 18 19 \section{Linear Partial Differential Equations} 20 \label{SEC LinearPDE} 21 22 The \LinearPDE class is used to define a general linear, steady, second order PDE 23 for an unknown function $u$ on a given $\Omega$ defined through a \Domain object. 24 In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes 25 the outer normal field on $\Gamma$. 26 27 For a single PDE with a solution with a single component the linear PDE is defined in the 28 following form: 29 \begin{equation}\label{LINEARPDE.SINGLE.1} 30 -(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 \; . 31 \end{equation} 32 $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. 33 The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through \Data objects in the 34 \Function on the PDE or objects that can be converted into such \Data objects. 35 $A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar. 36 The following natural 37 boundary conditions are considered \index{boundary condition!natural} on $\Gamma$: 38 \begin{equation}\label{LINEARPDE.SINGLE.2} 39 n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y \;. 40 \end{equation} 41 Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are 42 each a \Scalar in the \FunctionOnBoundary. Constraints \index{constraint} for the solution prescribing the value of the 43 solution at certain locations in the domain. They have the form 44 \begin{equation}\label{LINEARPDE.SINGLE.3} 45 u=r \mbox{ where } q>0 46 \end{equation} 47 $r$ and $q$ are each \Scalar where $q$ is the characteristic function 48 \index{characteristic function} defining where the constraint is applied. 49 The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other condition set by \eqn{LINEARPDE.SINGLE.1} 50 or \eqn{LINEARPDE.SINGLE.2}. 51 52 For a system of PDEs and a solution with several components the PDE has the form 53 \begin{equation}\label{LINEARPDE.SYSTEM.1} 54 -(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} \; . 55 \end{equation} 56 $A$ is a \RankFour, $B$ and $C$ are each a \RankThree, $D$ and $X$ are each a \RankTwo and $Y$ is a \RankOne. 57 The natural boundary conditions \index{boundary condition!natural} take the form: 58 \begin{equation}\label{LINEARPDE.SYSTEM.2} 59 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} \;. 60 \end{equation} 61 The coefficient $d$ is a \RankTwo and $y$ is a 62 \RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form 63 \begin{equation}\label{LINEARPDE.SYSTEM.3} 64 u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0 65 \end{equation} 66 $r$ and $q$ are each \RankOne. Notice that not necessarily all components must 67 have a constraint at all locations. 68 69 \LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$ 70 in the domain $\Omega$. To specify the conditions across the discontinuity we are using the 71 generalised flux $J$\footnote{In some applications the definition of flux used here can be different from the commonly used definition. For instance, if $T$ is a temperature field the heat flux $q$ is defined as $q\hackscore{,i}=-\kappa T\hackscore{,i}$ ($\kappa$ is diffusifity) which differs from the definition used here by the sign. This needs to be kept in mind when defining natural boundary conditions.\index{boundary condition!natural}} which is in the case of a systems of PDEs and several components of the solution 72 defined as 73 \begin{equation}\label{LINEARPDE.SYSTEM.5} 74 J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij} 75 \end{equation} 76 For the case of single solution component and single PDE $J$ is defined 77 \begin{equation}\label{LINEARPDE.SINGLE.5} 78 J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j} 79 \end{equation} 80 In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the 81 discontinuity pointing from side 0 towards side 1. For a system of PDEs 82 the contact condition takes the form 83 \begin{equation}\label{LINEARPDE.SYSTEM.6} 84 n\hackscore{j} J^{0}\hackscore{ij}=n\hackscore{j} J^{1}\hackscore{ij}=y^{contact}\hackscore{i} - d^{contact}\hackscore{ik} [u]\hackscore{k} \; . 85 \end{equation} 86 where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the 87 discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference 88 of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$. 89 The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a 90 \RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne. 91 In case of a single PDE and a single component solution the contact condition takes the form 92 \begin{equation}\label{LINEARPDE.SINGLE.6} 93 n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u] 94 \end{equation} 95 In this case the the coefficient $d^{contact}$ and $y^{contact}$ are each \Scalar 96 both in the \FunctionOnContactZero or \FunctionOnContactOne. 97 98 The PDE is symmetrical \index{symmetrical} if 99 \begin{equation}\label{LINEARPDE.SINGLE.4} 100 A\hackscore{jl}=A\hackscore{lj} \mbox{ and } B\hackscore{j}=C\hackscore{j} 101 \end{equation} 102 The system of PDEs is symmetrical \index{symmetrical} if 103 \begin{eqnarray} 104 \label{LINEARPDE.SYSTEM.4} 105 A\hackscore{ijkl}&=&A\hackscore{klij} \\ 106 B\hackscore{ijk}&=&C\hackscore{kij} \\ 107 D\hackscore{ik}&=&D\hackscore{ki} \\ 108 d\hackscore{ik}&=&d\hackscore{ki} \\ 109 d^{contact}\hackscore{ik}&=&d^{contact}\hackscore{ki} 110 \end{eqnarray} 111 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. 113 114 The following example illustrates the typical usage of the \LinearPDE class: 115 \begin{python} 116 from esys.escript import * 117 from esys.escript.linearPDEs import LinearPDE 118 from esys.finley import Rectangle 119 mydomain = Rectangle(l0=1.,l1=1.,n0=40, n1=20) 120 mypde=LinearPDE(mydomain) 121 mypde.setSymmetryOn() 122 mypde.setValue(A=kappa*kronecker(mydomain),D=1,Y=1) 123 u=mypde.getSolution() 124 \end{python} 125 We refer to chapter~\ref{CHAP: Tutorial} for more details. 126 127 An instance of the \SolverOptions class is attached to the \LinearPDE class object. It is used to set options of the solver used to solve the PDE. In the following 128 code the \method{getSolverOptions} is used to access the \SolverOptions 129 attached to \var{mypde}: 130 \begin{python} 131 from esys.escript import * 132 from esys.escript.linearPDEs import LinearPDE, SolverOptions 133 from esys.finley import Rectangle 134 mydomain = Rectangle(l0=1.,l1=1.,n0=40, n1=20) 135 mypde=LinearPDE(mydomain) 136 mypde.setValue(A=kappa*kronecker(mydomain),D=1,Y=1) 137 mypde.getSolverOptions().setVerbosityOn() 138 mypde.getSolverOptions().setSolverMethod(SolverOptions.PCG) 139 mypde.getSolverOptions().setPreconditioner(SolverOptions.AMG) 140 mypde.getSolverOptions().setTolerance(1e-8) 141 mypde.getSolverOptions().setIterMax(1000) 142 u=mypde.getSolution() 143 \end{python} 144 In this code the preconditoned conjugate gradient method \PCG 145 with preconditioner \AMG. The relative tolerance is set tto $10^{-8}$ and 146 the maximum number of iteration steps to $1000$. 147 148 Moreover, after a completed solution call 149 the attached \SolverOptions object gives access to diagnostic informations: 150 \begin{python} 151 u=mypde.getSolution() 152 print 'Number of iteration steps =', mypde.getDiagnostics('num_iter') 153 print 'Total solution time =', mypde.getDiagnostics('time') 154 print 'Set-up time =', mypde.getDiagnostics('set_up_time') 155 print 'Residual norm of returned solution =', mypde.getDiagnostics('residual_norm') 156 \end{python} 157 Typically a negative value for a diagnostic value indicates that the value is undefined. 158 159 \subsection{Classes} 160 \declaremodule{extension}{esys.escript.linearPDEs} 161 \modulesynopsis{Linear partial differential equation handler} 162 The module \linearPDEs provides an interface to define and solve linear partial 163 differential equations within \escript. The module \linearPDEs does not provide any 164 solver capabilities in itself but hands the PDE over to 165 the PDE solver library defined through the \Domain of the PDE, eg. \finley. 166 The general interface is provided through the \LinearPDE class. The \Poisson 167 class which is also derived form the \LinearPDE class should be used 168 to define the Poisson equation \index{Poisson}. 169 170 \subsection{\LinearPDE class} 171 This is the general class to define a linear PDE in \escript. We list a selection of the most 172 important methods of the class. For a complete list, see the reference at \ReferenceGuide. 173 174 \begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0} 175 opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations} 176 and \var{numSolutions} gives the number of equations and the number of solution components. 177 If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations 178 and the number solutions, respectively, stay undefined until a coefficient is 179 defined. 180 \end{classdesc} 181 182 \subsubsection{\LinearPDE methods} 183 184 \begin{methoddesc}[LinearPDE]{setValue}{ 185 \optional{A}\optional{, B}, 186 \optional{, C}\optional{, D} 187 \optional{, X}\optional{, Y} 188 \optional{, d}\optional{, y} 189 \optional{, d_contact}\optional{, y_contact} 190 \optional{, q}\optional{, r}} 191 assigns new values to coefficients. By default all values are assumed to be zero\footnote{ 192 In fact it is assumed they are not present by assigning the value \code{escript.Data()}. The 193 can by used by the solver library to reduce computational costs. 194 } 195 If the new coefficient value is not a \Data object, it is converted into a \Data object in the 196 appropriate \FunctionSpace. 197 \end{methoddesc} 198 199 \begin{methoddesc}[LinearPDE]{getCoefficient}{name} 200 return the value assigned to coefficient \var{name}. If \var{name} is not a valid name 201 an exception is raised. 202 \end{methoddesc} 203 204 \begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name} 205 returns the shape of coefficient \var{name} even if no value has been assigned to it. 206 \end{methoddesc} 207 208 \begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name} 209 returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it. 210 \end{methoddesc} 211 212 \begin{methoddesc}[LinearPDE]{setDebugOn}{} 213 switches on debug mode. 214 \end{methoddesc} 215 216 \begin{methoddesc}[LinearPDE]{setDebugOff}{} 217 switches off debug mode. 218 \end{methoddesc} 219 220 \begin{methoddesc}[LinearPDE]{getSolverOptions}{} 221 returns the solver options for solving the PDE. In fact the method returns 222 a \SolverOptions class object which can be used to modify the tolerance, 223 the solver or the preconditioner, see Section~\ref{SEC Solver Options} for details. 224 \end{methoddesc} 225 226 \begin{methoddesc}[LinearPDE]{setSolverOptions}{\optional{options=None}} 227 sets the solver options for solving the PDE. If argument \var{options} is present it 228 must be a \SolverOptions class object, see Section~\ref{SEC Solver Options} for details. Otherwise the solver options are reset to the default. 229 \end{methoddesc} 230 231 232 \begin{methoddesc}[LinearPDE]{isUsingLumping}{} 233 returns \True if \LUMPING is set as the solver for the system of linear equations. 234 Otherwise \False is returned. 235 \end{methoddesc} 236 237 238 \begin{methoddesc}[LinearPDE]{getDomain}{} 239 returns the \Domain of the PDE. 240 \end{methoddesc} 241 242 \begin{methoddesc}[LinearPDE]{getDim}{} 243 returns the spatial dimension of the PDE. 244 \end{methoddesc} 245 246 \begin{methoddesc}[LinearPDE]{getNumEquations}{} 247 returns the number of equations. 248 \end{methoddesc} 249 250 \begin{methoddesc}[LinearPDE]{getNumSolutions}{} 251 returns the number of components of the solution. 252 \end{methoddesc} 253 254 \begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False} 255 returns \True if the PDE is symmetric and \False otherwise. 256 The method is very computationally expensive and should only be 257 called for testing purposes. The symmetry flag is not altered. 258 If \var{verbose}=\True information about where symmetry is violated 259 are printed. 260 \end{methoddesc} 261 262 \begin{methoddesc}[LinearPDE]{getFlux}{u} 263 returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u} 264 defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively. 265 \end{methoddesc} 266 267 268 \begin{methoddesc}[LinearPDE]{isSymmetric}{} 269 returns \True if the PDE has been indicated to be symmetric. 270 Otherwise \False is returned. 271 \end{methoddesc} 272 273 \begin{methoddesc}[LinearPDE]{setSymmetryOn}{} 274 indicates that the PDE is symmetric. 275 \end{methoddesc} 276 277 \begin{methoddesc}[LinearPDE]{setSymmetryOff}{} 278 indicates that the PDE is not symmetric. 279 \end{methoddesc} 280 281 \begin{methoddesc}[LinearPDE]{setReducedOrderOn}{} 282 switches on the reduction of polynomial order for the solution and equation evaluation even if 283 a quadratic or higher interpolation order is defined in the \Domain. This feature may not 284 be supported by all PDE libraries. 285 \end{methoddesc} 286 287 \begin{methoddesc}[LinearPDE]{setReducedOrderOff}{} 288 switches off the reduction of polynomial order for the solution and 289 equation evaluation. 290 \end{methoddesc} 291 292 \begin{methoddesc}[LinearPDE]{getOperator}{} 293 returns the \Operator of the PDE. 294 \end{methoddesc} 295 296 \begin{methoddesc}[LinearPDE]{getRightHandSide}{} 297 returns the right hand side of the PDE as a \Data object. If 298 \var{ignoreConstraint}=\True, then the constraints are not considered 299 when building up the right hand side. 300 \end{methoddesc} 301 302 \begin{methoddesc}[LinearPDE]{getSystem}{} 303 returns the \Operator and right hand side of the PDE. 304 \end{methoddesc} 305 306 \begin{methoddesc}[LinearPDE]{getSolution}{} 307 returns (an approximation of) the solution of the PDE. This call 308 will invoke the discretization of the PDE and the solution of the resulting 309 system of linear equations. Keep in mind that this call is typically computational 310 expensive and can - depending on the PDE and the discretiztion - take a long time to complete. 311 \end{methoddesc} 312 313 314 315 \subsection{The \Poisson Class} 316 The \Poisson class provides an easy way to define and solve the Poisson 317 equation 318 \begin{equation}\label{POISSON.1} 319 -u\hackscore{,ii}=f\; . 320 \end{equation} 321 with homogeneous boundary conditions 322 \begin{equation}\label{POISSON.2} 323 n\hackscore{i}u\hackscore{,i}=0 324 \end{equation} 325 and homogeneous constraints 326 \begin{equation}\label{POISSON.3} 327 u=0 \mbox{ where } q>0 328 \end{equation} 329 $f$ has to be a \Scalar in the \Function and $q$ must be 330 a \Scalar in the \SolutionFS. 331 332 \begin{classdesc}{Poisson}{domain} 333 opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE. 334 \end{classdesc} 335 \begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()} 336 assigns new values to \var{f} and \var{q}. 337 \end{methoddesc} 338 339 \subsection{The \Helmholtz Class} 340 The \Helmholtz class defines the Helmholtz problem 341 \begin{equation}\label{HZ.1} 342 \omega \; u - (k\; u\hackscore{,j})\hackscore{,j} = f 343 \end{equation} 344 with natural boundary conditions 345 \begin{equation}\label{HZ.2} 346 k\; u\hackscore{,j} n\hackscore{,j} = g- \alpha \; u 347 \end{equation} 348 and constraints: 349 \begin{equation}\label{HZ.3} 350 u=r \mbox{ where } q>0 351 \end{equation} 352 $\omega$, $k$, $f$ have to be a \Scalar in the \Function, 353 $g$ and $\alpha$ must be a \Scalar in the \FunctionOnBoundary, 354 and $q$ and $r$ must be a \Scalar in the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace. 355 356 \begin{classdesc}{Helmholtz}{domain} 357 opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE. 358 \end{classdesc} 359 \begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}} 360 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. 361 \end{methoddesc} 362 363 \subsection{The \Lame Class} 364 The \Lame class defines a Lame equation problem: 365 \begin{equation}\label{LE.1} 366 -\mu (u\hackscore{i,j}+u\hackscore{j,i})+\lambda u\hackscore{k,k})\hackscore{j} = F\hackscore{i}-\sigma\hackscore{ij,j} 367 \end{equation} 368 with natural boundary conditions: 369 \begin{equation}\label{LE.2} 370 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} 371 \end{equation} 372 and constraint 373 \begin{equation}\label{LE.3} 374 u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0 375 \end{equation} 376 $\mu$, $\lambda$ have to be a \Scalar in the \Function, 377 $F$ has to be a \Vector in the \Function, 378 $\sigma$ has to be a \Tensor in the \Function, 379 $f$ must be a \Vector in the \FunctionOnBoundary, 380 and $q$ and $r$ must be a \Vector in the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace. 381 382 \begin{classdesc}{Lame}{domain} 383 opens a Lame equation on the \Domain domain. \Lame is derived from \LinearPDE. 384 \end{classdesc} 385 \begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}} 386 assigns new values to 387 \var{lame_lambda}, 388 \var{lame_mu}, 389 \var{F}, 390 \var{sigma}, 391 \var{f}, 392 \var{r} and 393 \var{q} 394 By default all values are set to be zero. 395 \end{methoddesc} 396 397 % \section{Transport Problems} 398 % \label{SEC Transport} 399 400 \section{Solver Options} 401 \label{SEC Solver Options} 402 403 \begin{classdesc}{SolverOptions}{} 404 This class defines the solver options for a linear or non-linear solver. 405 The option also supports the handling of diagnostic informations. 406 \end{classdesc} 407 408 \begin{methoddesc}[SolverOptions]{getSummary}{} 409 Returns a string reporting the current settings 410 \end{methoddesc} 411 412 \begin{methoddesc}[SolverOptions]{getName}{key} 413 Returns the name as a string of a given key 414 \end{methoddesc} 415 416 \begin{methoddesc}[SolverOptions]{setSolverMethod}{\optional{method=SolverOptions.DEFAULT}} 417 Sets the solver method to be used. Use \var{method}=\member{SolverOptions.DIRECT} to indicate that a direct rather than an iterative solver should be used and use \var{method}=\member{SolverOptions.ITERATIVE} to indicate that an iterative rather than a direct solver should be used. 418 The value of \var{method} must be one of the constants 419 \member{SolverOptions.DEFAULT}, \member{SolverOptions.DIRECT}, \member{SolverOptions.CHOLEVSKY}, \member{SolverOptions.PCG},\member{SolverOptions.CR}, \member{SolverOptions.CGS}, \member{SolverOptions.BICGSTAB}, \member{SolverOptions.SSOR}, 420 \member{SolverOptions.GMRES}, \member{SolverOptions.PRES20}, \member{SolverOptions.LUMPING}, \member{SolverOptions.ITERATIVE}, \member{SolverOptions.AMG}, \member{SolverOptions.NONLINEAR_GMRES}, \member{SolverOptions.TFQMR}, \member{SolverOptions.MINRES}, 421 or \member{SolverOptions.GAUSS_SEIDEL}. 422 Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters. See Table~\ref{TAB FINLEY SOLVER OPTIONS 1} for the solvers supported by \finley. 423 \end{methoddesc} 424 425 \begin{methoddesc}[SolverOptions]{getSolverMethod}{} 426 Returns key of the solver method to be used. 427 \end{methoddesc} 428 429 \begin{methoddesc}[SolverOptions]{setPreconditioner}{\optional{preconditioner=SolverOptions.JACOBI}} 430 Sets the preconditioner to be used. 431 The value of \var{preconditioner} must be one of the constants 432 \member{SolverOptions.SSOR}, \member{SolverOptions.ILU0}, \member{SolverOptions.ILUT}, \member{SolverOptions.JACOBI}, 433 \member{SolverOptions.AMG}, \member{SolverOptions.REC_ILU}, \member{SolverOptions.GAUSS_SEIDEL}, \member{SolverOptions.RILU}, or 434 \member{SolverOptions.NO_PRECONDITIONER}. 435 Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters 436 an unknown preconditioner. See Table~\ref{TAB FINLEY SOLVER OPTIONS 2} for the solvers supported by \finley. 437 \end{methoddesc} 438 439 \begin{methoddesc}[SolverOptions]{getPreconditioner}{} 440 Returns key of the preconditioner to be used. 441 \end{methoddesc} 442 443 \begin{methoddesc}[SolverOptions]{setPackage}{\optional{package=SolverOptions.DEFAULT}} 444 Sets the solver package to be used as a solver. 445 The value of \var{method} must be one of the constants in \member{SolverOptions.DEFAULT}, \member{SolverOptions.PASO}, \member{SolverOptions.SUPER_LU}, \member{SolverOptions.PASTIX}, \member{SolverOptions.MKL}, \member{SolverOptions.UMFPACK}, \member{SolverOptions.TRILINOS}. 446 Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular package is requested. Currently \finley supports \member{SolverOptions.PASO} (as default) 447 and, if available, \member{SolverOptions.MKL} and \member{SolverOptions.UMFPACK}. 448 \end{methoddesc} 449 450 \begin{methoddesc}[SolverOptions]{getPackage}{} 451 Returns the solver package key 452 \end{methoddesc} 453 454 455 \begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}} 456 resets the diagnostics. If \var{all} is \True all diagnostics including accumulative counters are reset. 457 \end{methoddesc} 458 459 \begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}} 460 Returns the diagnostic information \var{name}. The following keywords are 461 supported: 462 \begin{itemize} 463 \item "num_iter": the number of iteration steps 464 \item "cum_num_iter": the cumulative number of iteration steps 465 \item "num_level": the number of level in multi level solver 466 \item "num_inner_iter": the number of inner iteration steps 467 \item"cum_num_inner_iter": the cumulative number of inner iteration steps 468 \item"time": execution time 469 \item "cum_time": cumulative execution time 470 \item "set_up_time": time to set up of the solver, typically this includes factorization and reordering 471 \item "cum_set_up_time": cumulative time to set up of the solver 472 \item "residual_norm": norm of the final residual 473 \item "converged": return self.__converged 474 \end{itemize} 475 \end{methoddesc} 476 477 478 \begin{methoddesc}[SolverOptions]{hasConverged}{} 479 Returns \True if the last solver call has been finalized successfully. 480 If an exception has been thrown by the solver the status of this flag is undefined. 481 \end{methoddesc} 482 483 \begin{methoddesc}[SolverOptions]{setCoarsening}{\optional{method=SolverOptions.DEFAULT}} 484 Sets the key of the coarsening method to be applied in \AMG. 485 The value of \var{method} must be one of the constants 486 \member{SolverOptions.DEFAULT} 487 \member{SolverOptions.YAIR_SHAPIRA_COARSENING}, 488 \member{SolverOptions.RUGE_STUEBEN_COARSENING}, or \member{SolverOptions.AGGREGATION_COARSENING}. 489 \end{methoddesc} 490 491 \begin{methoddesc}[SolverOptions]{getCoarsening}{} 492 Returns the key of the coarsening algorithm to be applied \AMG. 493 \end{methoddesc} 494 495 \begin{methoddesc}[SolverOptions]{setReordering}{\optional{ordering=SolverOptions.DEFAULT_REORDERING}} 496 Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering to optimize compute time and storage use during elimination. The value of \var{ordering} must be one of the constants 497 \member{SolverOptions.NO_REORDERING}, \member{SolverOptions.MINIMUM_FILL_IN}, 498 \member{SolverOptions.NESTED_DISSECTION}, or \member{SolverOptions.DEFAULT_REORDERING}. 499 \end{methoddesc} 500 501 \begin{methoddesc}[SolverOptions]{getReordering}{} 502 Returns the key of the reordering method to be applied if supported by the solver. 503 \end{methoddesc} 504 505 \begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}} 506 Sets the number of iterations steps after which \GMRES is performing a restart. 507 If \var{restart} is equal to \var{None} no restart is performed. 508 \end{methoddesc} 509 510 511 \begin{methoddesc}[SolverOptions]{getRestart}{} 512 Returns the number of iterations steps after which \GMRES is performing a restart. 513 \end{methoddesc} 514 515 \begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}} 516 Sets the number of residuals in \GMRES to be stored for orthogonalization. The more residuals are stored the faster \GMRES converged but 517 \end{methoddesc} 518 519 \begin{methoddesc}[SolverOptions]{getTruncation}{} 520 Returns the number of residuals in \GMRES to be stored for orthogonalization 521 \end{methoddesc} 522 523 524 \begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}} 525 Sets the maximum number of iteration steps 526 \end{methoddesc} 527 528 \begin{methoddesc}[SolverOptions]{getIterMax}{} 529 Returns maximum number of iteration steps 530 \end{methoddesc} 531 532 \begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}} 533 Sets the maximum number of coarsening levels to be used in the \AMG solver or preconditioner. 534 \end{methoddesc} 535 536 \begin{methoddesc}[SolverOptions]{getLevelMax}{} 537 Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner 538 \end{methoddesc} 539 540 \begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.05}} 541 Sets the threshold for coarsening in the \AMG solver or preconditioner 542 \end{methoddesc} 543 544 \begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{} 545 Returns the threshold for coarsening in the \AMG solver or preconditioner 546 \end{methoddesc} 547 548 \begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}} 549 Sets the minumum size of the coarsest level matrix in AMG. 550 \end{methoddesc} 551 552 \begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{} 553 Returns the minumum size of the coarsest level matrix in AMG. 554 \end{methoddesc} 555 556 \begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}} 557 Sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner. 558 \end{methoddesc} 559 560 \begin{methoddesc}[SolverOptions]{getNumSweeps}{} 561 Returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner. 562 \end{methoddesc} 563 564 \begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}} 565 Sets the number of sweeps in the pre-smoothing step of \AMG 566 \end{methoddesc} 567 568 \begin{methoddesc}[SolverOptions]{getNumPreSweeps}{} 569 Returns the number of sweeps in the pre-smoothing step of \AMG 570 \end{methoddesc} 571 572 \begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}} 573 Sets the number of sweeps in the post-smoothing step of \AMG 574 \end{methoddesc} 575 576 \begin{methoddesc}[SolverOptions]{getNumPostSweeps}{} 577 Returns he number of sweeps sweeps in the post-smoothing step of \AMG 578 \end{methoddesc} 579 580 \begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}} 581 Sets the relative tolerance for the solver. The actually meaning of tolerance depends 582 on the underlying PDE library. In most cases, the tolerance 583 will only consider the error from solving the discrete problem but will 584 not consider any discretization error. 585 \end{methoddesc} 586 587 \begin{methoddesc}[SolverOptions]{getTolerance}{} 588 Returns the relative tolerance for the solver 589 \end{methoddesc} 590 591 \begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}} 592 Sets the absolute tolerance for the solver. The actually meaning of tolerance depends 593 on the underlying PDE library. In most cases, the tolerance 594 will only consider the error from solving the discrete problem but will 595 not consider any discretization error. 596 \end{methoddesc} 597 598 \begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{} 599 Returns the absolute tolerance for the solver 600 \end{methoddesc} 601 602 603 \begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}} 604 Sets the relative tolerance for an inner iteration scheme for instance 605 on the coarsest level in a multi-level scheme. 606 \end{methoddesc} 607 608 \begin{methoddesc}[SolverOptions]{getInnerTolerance}{} 609 Returns the relative tolerance for an inner iteration scheme 610 \end{methoddesc} 611 612 \begin{methoddesc}[SolverOptions]{setDropTolerance}{\optional{drop_tol=0.01}} 613 Sets the relative drop tolerance in ILUT 614 \end{methoddesc} 615 616 \begin{methoddesc}[SolverOptions]{getDropTolerance}{} 617 Returns the relative drop tolerance in \ILUT 618 \end{methoddesc} 619 620 621 \begin{methoddesc}[SolverOptions]{setDropStorage}{\optional{storage=2.}} 622 Sets the maximum allowed increase in storage for \ILUT. \var{storage}=2 would mean that a doubling of the storage needed for the coefficient matrix is allowed in the \ILUT factorization. 623 \end{methoddesc} 624 625 \begin{methoddesc}[SolverOptions]{getDropStorage}{} 626 Returns the maximum allowed increase in storage for \ILUT 627 \end{methoddesc} 628 629 \begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}} 630 Sets the relaxation factor used to add dropped elements in \RILU to the main diagonal. 631 \end{methoddesc} 632 633 \begin{methoddesc}[SolverOptions]{getRelaxationFactor}{} 634 Returns the relaxation factor used to add dropped elements in RILU to the main diagonal. 635 \end{methoddesc} 636 637 \begin{methoddesc}[SolverOptions]{isSymmetric}{} 638 Returns \True is the descrete system is indicated as symmetric. 639 \end{methoddesc} 640 641 \begin{methoddesc}[SolverOptions]{setSymmetryOn}{} 642 Sets the symmetry flag to indicate that the coefficient matrix is symmetric. 643 \end{methoddesc} 644 645 \begin{methoddesc}[SolverOptions]{setSymmetryOff}{} 646 Clears the symmetry flag for the coefficient matrix. 647 \end{methoddesc} 648 649 \begin{methoddesc}[SolverOptions]{isVerbose}{} 650 Returns \True if the solver is expected to be verbose. 651 \end{methoddesc} 652 653 654 \begin{methoddesc}[SolverOptions]{setVerbosityOn}{} 655 Switches the verbosity of the solver on. 656 \end{methoddesc} 657 658 659 \begin{methoddesc}[SolverOptions]{setVerbosityOff}{} 660 Switches the verbosity of the solver off. 661 \end{methoddesc} 662 663 664 \begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{} 665 Returns \True if the tolerance of the inner solver is selected automatically. 666 Otherwise the inner tolerance set by \member{setInnerTolerance} is used. 667 \end{methoddesc} 668 669 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{} 670 Switches the automatic selection of inner tolerance on 671 \end{methoddesc} 672 673 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{} 674 Switches the automatic selection of inner tolerance off. 675 \end{methoddesc} 676 677 \begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}} 678 Sets the maximum number of iteration steps for the inner iteration. 679 \end{methoddesc} 680 681 \begin{methoddesc}[SolverOptions]{getInnerIterMax}{} 682 Returns maximum number of inner iteration steps. 683 \end{methoddesc} 684 685 \begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{} 686 Returns \True if a failure to meet the stopping criteria within the 687 given number of iteration steps is not raising in exception. This is useful 688 if a solver is used in a non-linear context where the non-linear solver can 689 continue even if the returned the solution does not necessarily meet the 690 stopping criteria. One can use the \member{hasConverged} method to check if the 691 last call to the solver was successful. 692 \end{methoddesc} 693 694 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{} 695 Switches the acceptance of a failure of convergence on. 696 \end{methoddesc} 697 698 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{} 699 Switches the acceptance of a failure of convergence off. 700 \end{methoddesc} 701 702 \begin{memberdesc}[SolverOptions]{DEFAULT} 703 default method, preconditioner or package to be used to solve the PDE. An appropriate method should be 704 chosen by the used PDE solver library. 705 \end{memberdesc} 706 707 \begin{memberdesc}[SolverOptions]{MKL} 708 the \MKL library by Intel,~\Ref{MKL}\footnote{The \MKL library will only be available when the Intel compilation environment is used.}. 709 \end{memberdesc} 710 711 \begin{memberdesc}[SolverOptions]{UMFPACK} 712 the \UMFPACK,~\Ref{UMFPACK}. Remark: \UMFPACK is not parallelized. 713 \end{memberdesc} 714 715 \begin{memberdesc}[SolverOptions]{PASO} 716 \PASO is the solver library of \finley, see \Sec{CHAPTER ON FINLEY}. 717 \end{memberdesc} 718 719 \begin{memberdesc}[SolverOptions]{ITERATIVE} 720 the default iterative method and preconditioner. The actually used method depends on the PDE solver library and the solver package been chosen. Typically, \PCG is used for symmetric PDEsand \BiCGStab otherwise, both with \JACOBI preconditioner. 721 \end{memberdesc} 722 723 \begin{memberdesc}[SolverOptions]{DIRECT} 724 the default direct linear solver. 725 \end{memberdesc} 726 727 \begin{memberdesc}[SolverOptions]{CHOLEVSKY} 728 direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE. 729 \end{memberdesc} 730 731 \begin{memberdesc}[SolverOptions]{PCG} 732 preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE. 733 \end{memberdesc} 734 735 \begin{memberdesc}[SolverOptions]{TFQMR} 736 transpose-free quasi-minimal residual method, see~\Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}. \end{memberdesc} 737 738 \begin{memberdesc}[SolverOptions]{GMRES} 739 the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters 740 \var{truncation} and \var{restart} of \method{getSolution}. 741 \end{memberdesc} 742 743 \begin{memberdesc}[SolverOptions]{MINRES} 744 minimal residual method method, \index{linear solver!MINRES}\index{MINRES} \end{memberdesc} 745 746 \begin{memberdesc}[SolverOptions]{LUMPING} 747 uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique 748 condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when 749 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 750 but is expected to converge to zero when the mesh gets finer. 751 Lumping does not use the linear system solver library. 752 \end{memberdesc} 753 754 \begin{memberdesc}[SolverOptions]{PRES20} 755 the GMRES method with truncation after five residuals and 756 restart after 20 steps, see~\Ref{WEISS}. 757 \end{memberdesc} 758 759 \begin{memberdesc}[SolverOptions]{CGS} 760 conjugate gradient squared method, see~\Ref{WEISS}. 761 \end{memberdesc} 762 763 \begin{memberdesc}[SolverOptions]{BICGSTAB} 764 stabilized bi-conjugate gradients methods, see~\Ref{WEISS}. 765 \end{memberdesc} 766 767 \begin{memberdesc}[SolverOptions]{SSOR} 768 symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support 769 this as a solver. 770 \end{memberdesc} 771 772 \begin{memberdesc}[SolverOptions]{ILU0} 773 the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}. 774 \end{memberdesc} 775 776 \begin{memberdesc}[SolverOptions]{ILUT} 777 the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the LU-factorization element with 778 relative size less then \member{getDropTolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the 779 \member{getDropStorage}-fold of the stiffness matrix. \member{getDropTolerance} and \member{getDropStorage} are both set in the 780 \method{getSolution} call. 781 \end{memberdesc} 782 783 \begin{memberdesc}[SolverOptions]{JACOBI} 784 the Jacobi preconditioner, see~\Ref{Saad}. 785 \end{memberdesc} 786 787 788 \begin{memberdesc}[SolverOptions]{AMG} 789 the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used 790 in a preconditioner. 791 \end{memberdesc} 792 793 \begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL} 794 the symmetric Gauss-Seidel preconditioner, see~\Ref{Saad}. 795 \member{getNumSweeps()} is the number of sweeps used. 796 \end{memberdesc} 797 798 \begin{memberdesc}[SolverOptions]{RILU} 799 relaxed incomplete LU factorization preconditioner, see~\Ref{RELAXILU}. This method is similar to \ILU0 but dropped elements are added to the main diagonal 800 with the relaxation factor \member{getRelaxationFactor} 801 \end{memberdesc} 802 803 \begin{memberdesc}[SolverOptions]{REC_ILU} 804 recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILU0 but applies reordering during the factorization. 805 \end{memberdesc} 806 807 \begin{memberdesc}[SolverOptions]{NO_REORDERING} 808 no ordering is used during factorization. 809 \end{memberdesc} 810 811 \begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING} 812 the default reordering method during factorization. 813 \end{memberdesc} 814 815 \begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN} 816 applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or 817 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in. 818 \end{memberdesc} 819 820 \begin{memberdesc}[SolverOptions]{NESTED_DISSECTION} 821 applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or 822 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in. 823 \end{memberdesc} 824 825 \begin{memberdesc}[SolverOptions]{TRILINOS} 826 the Trilinos library is used as a solver~\Ref{TRILINOS} 827 \end{memberdesc} 828 829 \begin{memberdesc}[SolverOptions]{SUPER_LU} 830 the SuperLU library is used as a solver~\Ref{SuperLU} 831 \end{memberdesc} 832 833 \begin{memberdesc}[SolverOptions]{PASTIX} 834 the Pastix library is used as a solver~\Ref{PASTIX} 835 \end{memberdesc} 836 837 838 \begin{memberdesc}[SolverOptions]{YAIR_SHAPIRA_COARSENING} 839 \AMG coarsening method by Yair-Shapira 840 \end{memberdesc} 841 842 \begin{memberdesc}[SolverOptions]{RUGE_STUEBEN_COARSENING} \AMG coarsening method by Ruge and Stueben 843 \end{memberdesc} 844 845 \begin{memberdesc}[SolverOptions]{AGGREGATION_COARSENING} \AMG coarsening using (symmetric) aggregation 846 \end{memberdesc} 847 848 \begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER} 849 no preconditioner is applied. 850 \end{memberdesc} 851

Properties

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