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

Revision 2524 - (show annotations)
Wed Jul 8 00:39:26 2009 UTC (11 years ago) by artak
File MIME type: application/x-tex
File size: 37356 byte(s)
Minimum size of the coarsest level matrix option added to solver options

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % 4 % Copyright (c) 2003-2008 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().setMaxIter(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 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. 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. 447 \end{methoddesc} 448 449 \begin{methoddesc}[SolverOptions]{getPackage}{} 450 Returns the solver package key 451 \end{methoddesc} 452 453 454 \begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}} 455 resets the diagnostics. If \var{all} is \True all diagnostics including accumulative counters are reset. 456 \end{methoddesc} 457 458 \begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}} 459 Returns the diagnostic information \var{name}. The following keywords are 460 supported: 461 \begin{itemize} 462 \item "num_iter": the number of iteration steps 463 \item "cum_num_iter": the cumulative number of iteration steps 464 \item "num_level": the number of level in multi level solver 465 \item "num_inner_iter": the number of inner iteration steps 466 \item"cum_num_inner_iter": the cumulative number of inner iteration steps 467 \item"time": execution time 468 \item "cum_time": cumulative execution time 469 \item "set_up_time": time to set up of the solver, typically this includes factorization and reordering 470 \item "cum_set_up_time": cumulative time to set up of the solver 471 \item "residual_norm": norm of the final residual 472 \item "converged": return self.__converged 473 \end{itemize} 474 \end{methoddesc} 475 476 477 \begin{methoddesc}[SolverOptions]{hasConverged}{} 478 Returns \True if the last solver call has been finalized successfully. 479 If an exception has been thrown by the solver the status of this flag is undefined. 480 \end{methoddesc} 481 482 \begin{methoddesc}[SolverOptions]{setCoarsening}{\optional{method=SolverOptions.DEFAULT}} 483 Sets the key of the coarsening method to be applied in \AMG. 484 The value of \var{method} must be one of the constants 485 \member{SolverOptions.DEFAULT} 486 \member{SolverOptions.YAIR_SHAPIRA_COARSENING}, 487 \member{SolverOptions.RUGE_STUEBEN_COARSENING}, or \member{SolverOptions.AGGREGATION_COARSENING}. 488 \end{methoddesc} 489 490 \begin{methoddesc}[SolverOptions]{getCoarsening}{} 491 Returns the key of the coarsening algorithm to be applied \AMG. 492 \end{methoddesc} 493 494 \begin{methoddesc}[SolverOptions]{setReordering}{\optional{ordering=SolverOptions.DEFAULT_REORDERING}} 495 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 496 \member{SolverOptions.NO_REORDERING}, \member{SolverOptions.MINIMUM_FILL_IN}, 497 \member{SolverOptions.NESTED_DISSECTION}, or \member{SolverOptions.DEFAULT_REORDERING}. 498 \end{methoddesc} 499 500 \begin{methoddesc}[SolverOptions]{getReordering}{} 501 Returns the key of the reordering method to be applied if supported by the solver. 502 \end{methoddesc} 503 504 \begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}} 505 Sets the number of iterations steps after which \GMRES is performing a restart. 506 If \var{restart} is equal to \var{None} no restart is performed. 507 \end{methoddesc} 508 509 510 \begin{methoddesc}[SolverOptions]{getRestart}{} 511 Returns the number of iterations steps after which \GMRES is performing a restart. 512 \end{methoddesc} 513 514 \begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}} 515 Sets the number of residuals in \GMRES to be stored for orthogonalization. The more residuals are stored the faster \GMRES converged but 516 \end{methoddesc} 517 518 \begin{methoddesc}[SolverOptions]{getTruncation}{} 519 Returns the number of residuals in \GMRES to be stored for orthogonalization 520 \end{methoddesc} 521 522 523 \begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}} 524 Sets the maximum number of iteration steps 525 \end{methoddesc} 526 527 \begin{methoddesc}[SolverOptions]{getIterMax}{} 528 Returns maximum number of iteration steps 529 \end{methoddesc} 530 531 \begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}} 532 Sets the maximum number of coarsening levels to be used in the \AMG solver or preconditioner. 533 \end{methoddesc} 534 535 \begin{methoddesc}[SolverOptions]{getLevelMax}{} 536 Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner 537 \end{methoddesc} 538 539 \begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.05}} 540 Sets the threshold for coarsening in the \AMG solver or preconditioner 541 \end{methoddesc} 542 543 \begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{} 544 Returns the threshold for coarsening in the \AMG solver or preconditioner 545 \end{methoddesc} 546 547 \begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}} 548 Sets the minumum size of the coarsest level matrix in AMG. 549 \end{methoddesc} 550 551 \begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{} 552 Returns the minumum size of the coarsest level matrix in AMG. 553 \end{methoddesc} 554 555 \begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}} 556 Sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner. 557 \end{methoddesc} 558 559 \begin{methoddesc}[SolverOptions]{getNumSweeps}{} 560 Returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner. 561 \end{methoddesc} 562 563 \begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}} 564 Sets the number of sweeps in the pre-smoothing step of \AMG 565 \end{methoddesc} 566 567 \begin{methoddesc}[SolverOptions]{getNumPreSweeps}{} 568 Returns the number of sweeps in the pre-smoothing step of \AMG 569 \end{methoddesc} 570 571 \begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}} 572 Sets the number of sweeps in the post-smoothing step of \AMG 573 \end{methoddesc} 574 575 \begin{methoddesc}[SolverOptions]{getNumPostSweeps}{} 576 Returns he number of sweeps sweeps in the post-smoothing step of \AMG 577 \end{methoddesc} 578 579 \begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}} 580 Sets the relative tolerance for the solver. The actually meaning of tolerance depends 581 on the underlying PDE library. In most cases, the tolerance 582 will only consider the error from solving the discrete problem but will 583 not consider any discretization error. 584 \end{methoddesc} 585 586 \begin{methoddesc}[SolverOptions]{getTolerance}{} 587 Returns the relative tolerance for the solver 588 \end{methoddesc} 589 590 \begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}} 591 Sets the absolute tolerance for the solver. The actually meaning of tolerance depends 592 on the underlying PDE library. In most cases, the tolerance 593 will only consider the error from solving the discrete problem but will 594 not consider any discretization error. 595 \end{methoddesc} 596 597 \begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{} 598 Returns the absolute tolerance for the solver 599 \end{methoddesc} 600 601 602 \begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}} 603 Sets the relative tolerance for an inner iteration scheme for instance 604 on the coarsest level in a multi-level scheme. 605 \end{methoddesc} 606 607 \begin{methoddesc}[SolverOptions]{getInnerTolerance}{} 608 Returns the relative tolerance for an inner iteration scheme 609 \end{methoddesc} 610 611 \begin{methoddesc}[SolverOptions]{setDropTolerance}{\optional{drop_tol=0.01}} 612 Sets the relative drop tolerance in ILUT 613 \end{methoddesc} 614 615 \begin{methoddesc}[SolverOptions]{getDropTolerance}{} 616 Returns the relative drop tolerance in \ILUT 617 \end{methoddesc} 618 619 620 \begin{methoddesc}[SolverOptions]{setDropStorage}{\optional{storage=2.}} 621 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. 622 \end{methoddesc} 623 624 \begin{methoddesc}[SolverOptions]{getDropStorage}{} 625 Returns the maximum allowed increase in storage for \ILUT 626 \end{methoddesc} 627 628 \begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}} 629 Sets the relaxation factor used to add dropped elements in \RILU to the main diagonal. 630 \end{methoddesc} 631 632 \begin{methoddesc}[SolverOptions]{getRelaxationFactor}{} 633 Returns the relaxation factor used to add dropped elements in RILU to the main diagonal. 634 \end{methoddesc} 635 636 \begin{methoddesc}[SolverOptions]{isSymmetric}{} 637 Returns \True is the descrete system is indicated as symmetric. 638 \end{methoddesc} 639 640 \begin{methoddesc}[SolverOptions]{setSymmetryOn}{} 641 Sets the symmetry flag to indicate that the coefficient matrix is symmetric. 642 \end{methoddesc} 643 644 \begin{methoddesc}[SolverOptions]{setSymmetryOff}{} 645 Clears the symmetry flag for the coefficient matrix. 646 \end{methoddesc} 647 648 \begin{methoddesc}[SolverOptions]{isVerbose}{} 649 Returns \True if the solver is expected to be verbose. 650 \end{methoddesc} 651 652 653 \begin{methoddesc}[SolverOptions]{setVerbosityOn}{} 654 Switches the verbosity of the solver on. 655 \end{methoddesc} 656 657 658 \begin{methoddesc}[SolverOptions]{setVerbosityOff}{} 659 Switches the verbosity of the solver off. 660 \end{methoddesc} 661 662 663 \begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{} 664 Returns \True if the tolerance of the inner solver is selected automatically. 665 Otherwise the inner tolerance set by \member{setInnerTolerance} is used. 666 \end{methoddesc} 667 668 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{} 669 Switches the automatic selection of inner tolerance on 670 \end{methoddesc} 671 672 \begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{} 673 Switches the automatic selection of inner tolerance off. 674 \end{methoddesc} 675 676 \begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}} 677 Sets the maximum number of iteration steps for the inner iteration. 678 \end{methoddesc} 679 680 \begin{methoddesc}[SolverOptions]{getInnerIterMax}{} 681 Returns maximum number of inner iteration steps. 682 \end{methoddesc} 683 684 \begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{} 685 Returns \True if a failure to meet the stopping criteria within the 686 given number of iteration steps is not raising in exception. This is useful 687 if a solver is used in a non-linear context where the non-linear solver can 688 continue even if the returned the solution does not necessarily meet the 689 stopping criteria. One can use the \member{hasConverged} method to check if the 690 last call to the solver was successful. 691 \end{methoddesc} 692 693 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{} 694 Switches the acceptance of a failure of convergence on. 695 \end{methoddesc} 696 697 \begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{} 698 Switches the acceptance of a failure of convergence off. 699 \end{methoddesc} 700 701 \begin{memberdesc}[SolverOptions]{DEFAULT} 702 default method, preconditioner or package to be used to solve the PDE. An appropriate method should be 703 chosen by the used PDE solver library. 704 \end{memberdesc} 705 706 \begin{memberdesc}[SolverOptions]{MKL} 707 the MKL library by Intel,~\Ref{MKL}\footnote{The MKL library will only be available when the Intel compilation environment is used.}. 708 \end{memberdesc} 709 710 \begin{memberdesc}[SolverOptions]{UMFPACK} 711 the UMFPACK,~\Ref{UMFPACK}. Remark: UMFPACK is not parallelized. 712 \end{memberdesc} 713 714 \begin{memberdesc}[SolverOptions]{PASO} 715 the solver library of \finley, see \Sec{CHAPTER ON FINLEY}. 716 \end{memberdesc} 717 718 \begin{memberdesc}[SolverOptions]{ITERATIVE} 719 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. 720 \end{memberdesc} 721 722 \begin{memberdesc}[SolverOptions]{DIRECT} 723 the default direct linear solver. 724 \end{memberdesc} 725 726 \begin{memberdesc}[SolverOptions]{CHOLEVSKY} 727 direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE. 728 \end{memberdesc} 729 730 \begin{memberdesc}[SolverOptions]{PCG} 731 preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE. 732 \end{memberdesc} 733 734 \begin{memberdesc}[SolverOptions]{TFQMR} 735 transpose-free quasi-minimal residual method, see~\Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}. \end{memberdesc} 736 737 \begin{memberdesc}[SolverOptions]{GMRES} 738 the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters 739 \var{truncation} and \var{restart} of \method{getSolution}. 740 \end{memberdesc} 741 742 \begin{memberdesc}[SolverOptions]{MINRES} 743 minimal residual method method, \index{linear solver!MINRES}\index{MINRES} \end{memberdesc} 744 745 \begin{memberdesc}[SolverOptions]{LUMPING} 746 uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique 747 condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when 748 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 749 but is expected to converge to zero when the mesh gets finer. 750 Lumping does not use the linear system solver library. 751 \end{memberdesc} 752 753 \begin{memberdesc}[SolverOptions]{PRES20} 754 the GMRES method with truncation after five residuals and 755 restart after 20 steps, see~\Ref{WEISS}. 756 \end{memberdesc} 757 758 \begin{memberdesc}[SolverOptions]{CGS} 759 conjugate gradient squared method, see~\Ref{WEISS}. 760 \end{memberdesc} 761 762 \begin{memberdesc}[SolverOptions]{BICGSTAB} 763 stabilized bi-conjugate gradients methods, see~\Ref{WEISS}. 764 \end{memberdesc} 765 766 \begin{memberdesc}[SolverOptions]{SSOR} 767 symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support 768 this as a solver. 769 \end{memberdesc} 770 771 \begin{memberdesc}[SolverOptions]{ILU0} 772 the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}. 773 \end{memberdesc} 774 775 \begin{memberdesc}[SolverOptions]{ILUT} 776 the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the LU-factorization element with 777 relative size less then \member{getDropTolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the 778 \member{getDropStorage}-fold of the stiffness matrix. \member{getDropTolerance} and \member{getDropStorage} are both set in the 779 \method{getSolution} call. 780 \end{memberdesc} 781 782 \begin{memberdesc}[SolverOptions]{JACOBI} 783 the Jacobi preconditioner, see~\Ref{Saad}. 784 \end{memberdesc} 785 786 787 \begin{memberdesc}[SolverOptions]{AMG} 788 the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used 789 in a preconditioner. 790 \end{memberdesc} 791 792 \begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL} 793 the symmetric Gauss-Seidel preconditioner, see~\Ref{Saad}. 794 \member{getNumSweeps()} is the number of sweeps used. 795 \end{memberdesc} 796 797 \begin{memberdesc}[SolverOptions]{RILU} 798 relaxed incomplete LU factorization preconditioner, see~\Ref{RELAXILU}. This method is similar to \ILU0 but dropped elements are added to the main diagonal 799 with the relaxation factor \member{getRelaxationFactor} 800 \end{memberdesc} 801 802 \begin{memberdesc}[SolverOptions]{REC_ILU} 803 recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILU0 but applies reordering during the factorization. 804 \end{memberdesc} 805 806 \begin{memberdesc}[SolverOptions]{NO_REORDERING} 807 no ordering is used during factorization. 808 \end{memberdesc} 809 810 \begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING} 811 the default reordering method during factorization. 812 \end{memberdesc} 813 814 \begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN} 815 applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or 816 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in. 817 \end{memberdesc} 818 819 \begin{memberdesc}[SolverOptions]{NESTED_DISSECTION} 820 applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or 821 linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in. 822 \end{memberdesc} 823 824 \begin{memberdesc}[SolverOptions]{TRILINOS} 825 the Trilinos library is used as a solver~\Ref{TRILINOS} 826 \end{memberdesc} 827 828 \begin{memberdesc}[SolverOptions]{SUPER_LU} 829 the SuperLU library is used as a solver~\Ref{SuperLU} 830 \end{memberdesc} 831 832 \begin{memberdesc}[SolverOptions]{PASTIX} 833 the Pastix library is used as a solver~\Ref{PASTIX} 834 \end{memberdesc} 835 836 837 \begin{memberdesc}[SolverOptions]{YAIR_SHAPIRA_COARSENING} 838 \AMG coarsening method by Yair-Shapira 839 \end{memberdesc} 840 841 \begin{memberdesc}[SolverOptions]{RUGE_STUEBEN_COARSENING} \AMG coarsening method by Ruge and Stueben 842 \end{memberdesc} 843 844 \begin{memberdesc}[SolverOptions]{AGGREGATION_COARSENING} \AMG coarsening using (symmetric) aggregation 845 \end{memberdesc} 846 847 \begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER} 848 no preconditioner is applied. 849 \end{memberdesc} 850

## Properties

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