doc/user/linearPDE.tex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (c) 2003-2009 by University of Queensland
% Earth Systems Science Computational Center (ESSCC)
% http://www.uq.edu.au/esscc
%
% Primary Business: Queensland, Australia
% Licensed under the Open Software License version 3.0
% http://www.opensource.org/licenses/osl-3.0.php
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\chapter{The Module \linearPDEs}


\section{Linear Partial Differential Equations}
\label{SEC LinearPDE}

The \LinearPDE class is used to define a general linear, steady, second order PDE
for an unknown function $u$ on a given $\Omega$ defined through a \Domain object.
In the following $\Gamma$ denotes the boundary of the domain $\Omega$. $n$ denotes
the outer normal field on $\Gamma$.

For a single PDE with a solution with a single component the linear PDE is defined in the
following form:
\begin{equation}\label{LINEARPDE.SINGLE.1}
-(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 \; .
\end{equation}
$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.
The coefficients $A$, $B$, $C$, $D$, $X$ and $Y$ have to be specified through \Data objects in the
\Function on the PDE or objects that can be converted into such \Data objects.
$A$ is a \RankTwo, $B$, $C$ and $X$ are \RankOne and $D$ and $Y$ are scalar.
The following natural
boundary conditions are considered \index{boundary condition!natural} on $\Gamma$:
\begin{equation}\label{LINEARPDE.SINGLE.2}
n\hackscore{j}(A\hackscore{jl} u\hackscore{,l}+B\hackscore{j} u)+d u=n\hackscore{j}X\hackscore{j} + y  \;.
\end{equation}
Notice that the coefficients $A$, $B$ and $X$ are defined in the PDE. The coefficients $d$ and $y$ are
each a \Scalar in the \FunctionOnBoundary.  Constraints \index{constraint} for the solution prescribing the value of the
solution at certain locations in the domain. They have the form
\begin{equation}\label{LINEARPDE.SINGLE.3}
u=r \mbox{ where } q>0
\end{equation}
$r$ and $q$ are each \Scalar where $q$ is the characteristic function
\index{characteristic function} defining where the constraint is applied.
The constraints defined by \eqn{LINEARPDE.SINGLE.3} override any other condition set by \eqn{LINEARPDE.SINGLE.1}
or \eqn{LINEARPDE.SINGLE.2}.

For a system of PDEs and a solution with several components the PDE has the form
\begin{equation}\label{LINEARPDE.SYSTEM.1}
-(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} \; .
\end{equation}
$A$ is a \RankFour, $B$ and $C$ are each a \RankThree, $D$ and $X$ are each a \RankTwo and $Y$ is a \RankOne.
The natural boundary conditions \index{boundary condition!natural} take the form:
\begin{equation}\label{LINEARPDE.SYSTEM.2}
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}  \;.
\end{equation}
The coefficient $d$ is a \RankTwo and $y$ is a
\RankOne both in the \FunctionOnBoundary. Constraints \index{constraint} take the form
\begin{equation}\label{LINEARPDE.SYSTEM.3}
u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
\end{equation}
$r$ and $q$ are each \RankOne. Notice that not necessarily all components must
have a constraint at all locations.

\LinearPDE also supports solution discontinuities \index{discontinuity} over contact region $\Gamma^{contact}$
in the domain $\Omega$. To specify the conditions across the discontinuity we are using the
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
defined as
\begin{equation}\label{LINEARPDE.SYSTEM.5}
J\hackscore{ij}=A\hackscore{ijkl}u\hackscore{k,l}+B\hackscore{ijk}u\hackscore{k}-X\hackscore{ij}
\end{equation}
For the case of single solution component and single PDE $J$ is defined
\begin{equation}\label{LINEARPDE.SINGLE.5}
J\hackscore{j}=A\hackscore{jl}u\hackscore{,l}+B\hackscore{j}u\hackscore{k}-X\hackscore{j}
\end{equation}
In the context of discontinuities \index{discontinuity} $n$ denotes the normal on the
discontinuity pointing from side 0 towards side 1. For a system of PDEs
the contact condition takes the form
\begin{equation}\label{LINEARPDE.SYSTEM.6}
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} \; .
\end{equation}
where $J^{0}$ and $J^{1}$ are the fluxes on side $0$ and side $1$ of the
discontinuity $\Gamma^{contact}$, respectively. $[u]$, which is the difference
of the solution at side 1 and at side 0, denotes the jump of $u$ across $\Gamma^{contact}$.
The coefficient $d^{contact}$ is a \RankTwo and $y^{contact}$ is a
\RankOne both in the \FunctionOnContactZero or \FunctionOnContactOne.
In case of a single PDE and a single component solution the contact condition takes the form
\begin{equation}\label{LINEARPDE.SINGLE.6}
n\hackscore{j} J^{0}\hackscore{j}=n\hackscore{j} J^{1}\hackscore{j}=y^{contact} - d^{contact}[u]
\end{equation}
In this case the the coefficient $d^{contact}$ and $y^{contact}$ are each \Scalar
both in the \FunctionOnContactZero or \FunctionOnContactOne.

The PDE is symmetrical \index{symmetrical} if
\begin{equation}\label{LINEARPDE.SINGLE.4}
A\hackscore{jl}=A\hackscore{lj} \mbox{ and } B\hackscore{j}=C\hackscore{j}
\end{equation}
The system of PDEs is symmetrical \index{symmetrical} if
\begin{eqnarray}
\label{LINEARPDE.SYSTEM.4}
A\hackscore{ijkl}&=&A\hackscore{klij} \\
B\hackscore{ijk}&=&C\hackscore{kij} \\
D\hackscore{ik}&=&D\hackscore{ki} \\
d\hackscore{ik}&=&d\hackscore{ki} \\
d^{contact}\hackscore{ik}&=&d^{contact}\hackscore{ki}
\end{eqnarray}
Note that in contrast with the scalar case~\eqn{LINEARPDE.SINGLE.4} now the coefficients $D$, $d$ abd $d^{contact}$
have to be inspected.

The following example illustrates the typical usage of the \LinearPDE class:
\begin{python}
from esys.escript import *
from esys.escript.linearPDEs import LinearPDE
from esys.finley import Rectangle
mydomain = Rectangle(l0=1.,l1=1.,n0=40, n1=20)
mypde=LinearPDE(mydomain)
mypde.setSymmetryOn()
mypde.setValue(A=kappa*kronecker(mydomain),D=1,Y=1)
u=mypde.getSolution()
\end{python}
We refer to chapter~\ref{CHAP: Tutorial} for more details.

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
code the \method{getSolverOptions} is used to access the  \SolverOptions 
attached to \var{mypde}:
\begin{python}
from esys.escript import *
from esys.escript.linearPDEs import LinearPDE, SolverOptions
from esys.finley import Rectangle
mydomain = Rectangle(l0=1.,l1=1.,n0=40, n1=20)
mypde=LinearPDE(mydomain)
mypde.setValue(A=kappa*kronecker(mydomain),D=1,Y=1)
mypde.getSolverOptions().setVerbosityOn()
mypde.getSolverOptions().setSolverMethod(SolverOptions.PCG)
mypde.getSolverOptions().setPreconditioner(SolverOptions.AMG)
mypde.getSolverOptions().setTolerance(1e-8)
mypde.getSolverOptions().setIterMax(1000)
u=mypde.getSolution()
\end{python}
In this code the preconditoned conjugate gradient method \PCG
with preconditioner \AMG. The relative tolerance is set tto $10^{-8}$ and
the maximum number of iteration steps to $1000$.

Moreover, after a completed solution call
the attached  \SolverOptions object gives access to diagnostic informations: 
\begin{python}
u=mypde.getSolution()
print 'Number of iteration steps =', mypde.getDiagnostics('num_iter')
print 'Total solution time =', mypde.getDiagnostics('time')
print 'Set-up time =', mypde.getDiagnostics('set_up_time')
print 'Net time =', mypde.getDiagnostics('net_time')
print 'Residual norm of returned solution =', mypde.getDiagnostics('residual_norm')
\end{python}
Typically a negative value for a diagnostic value indicates that the value is undefined.

\subsection{Classes}
\declaremodule{extension}{esys.escript.linearPDEs} 
\modulesynopsis{Linear partial differential equation handler}
The module \linearPDEs provides an interface to define and solve linear partial
differential equations within \escript. The module \linearPDEs does not provide any
solver capabilities in itself but hands the PDE over to
the PDE solver library defined through the \Domain of the PDE, eg. \finley.
The general interface is provided through the \LinearPDE class. The \Poisson
class which is also derived form the \LinearPDE class should be used
to define the Poisson equation \index{Poisson}.

\subsection{\LinearPDE class}
This is the general class to define a linear PDE in \escript. We list a selection of the most
important methods of the class. For a complete list, see the reference at \ReferenceGuide.

\begin{classdesc}{LinearPDE}{domain,numEquations=0,numSolutions=0}
opens a linear, steady, second order PDE on the \Domain \var{domain}. \var{numEquations}
and \var{numSolutions} gives the number of equations and the number of solution components.
If \var{numEquations} and \var{numSolutions} is non-positive, the number of equations
and the number solutions, respectively, stay undefined until a coefficient is
defined.
\end{classdesc}

\subsubsection{\LinearPDE methods}

\begin{methoddesc}[LinearPDE]{setValue}{
\optional{A}\optional{, B},
\optional{, C}\optional{, D}
\optional{, X}\optional{, Y}
\optional{, d}\optional{, y}
\optional{, d_contact}\optional{, y_contact}
\optional{, q}\optional{, r}}
assigns new values to coefficients. By default all values are assumed to be zero\footnote{
In fact it is assumed they are not present by assigning the value \code{escript.Data()}. The
can by used by the solver library to reduce computational costs.
}
If the new coefficient value is not a \Data object, it is converted into a \Data object in the
appropriate \FunctionSpace.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getCoefficient}{name}
return the value assigned to coefficient \var{name}. If \var{name} is not a valid name
an exception is raised.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getShapeOfCoefficient}{name}
returns the shape of coefficient \var{name} even if no value has been assigned to it.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getFunctionSpaceForCoefficient}{name}
returns the \FunctionSpace of coefficient \var{name} even if no value has been assigned to it.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setDebugOn}{}
switches on debug mode.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setDebugOff}{}
switches off debug mode.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getSolverOptions}{}
returns the solver options for solving the PDE. In fact the method returns
a \SolverOptions class object which can be used to modify the tolerance, 
the solver or the preconditioner, see Section~\ref{SEC Solver Options} for details.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setSolverOptions}{\optional{options=None}}
sets the solver options for solving the PDE. If argument \var{options} is present it
must be a \SolverOptions class object, see Section~\ref{SEC Solver Options} for details. Otherwise the solver options are reset to the default.
\end{methoddesc}


\begin{methoddesc}[LinearPDE]{isUsingLumping}{}
returns \True if \LUMPING is set as the solver for the system of linear equations.
Otherwise \False is returned.
\end{methoddesc}


\begin{methoddesc}[LinearPDE]{getDomain}{}
returns the \Domain of the PDE.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getDim}{}
returns the spatial dimension of the PDE.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getNumEquations}{}
returns the number of equations.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getNumSolutions}{}
returns the number of components of the solution.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{checkSymmetry}{verbose=\False}
returns \True if the PDE is symmetric and \False otherwise.
The method is very computationally expensive and should only be
called for testing purposes. The symmetry flag is not altered.
If \var{verbose}=\True information about where symmetry is violated
are printed.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getFlux}{u}
returns the flux $J\hackscore{ij}$ \index{flux} for given solution \var{u}
defined by \eqn{LINEARPDE.SYSTEM.5} and \eqn{LINEARPDE.SINGLE.5}, respectively.
\end{methoddesc}


\begin{methoddesc}[LinearPDE]{isSymmetric}{}
returns \True if the PDE has been indicated to be symmetric.
Otherwise \False is returned.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setSymmetryOn}{}
indicates that the PDE is symmetric.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setSymmetryOff}{}
indicates that the PDE is not symmetric.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setReducedOrderOn}{}
switches on the reduction of polynomial order for the solution and equation evaluation even if
a quadratic or higher interpolation order is defined in the \Domain. This feature may not
be supported by all PDE libraries.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{setReducedOrderOff}{}
switches off the reduction of polynomial order for the solution and
equation evaluation.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getOperator}{}
returns the \Operator of the PDE.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getRightHandSide}{}
returns the right hand side of the PDE as a \Data object. If
\var{ignoreConstraint}=\True, then the constraints are not considered
when building up the right hand side.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getSystem}{}
returns the \Operator and right hand side of the PDE.
\end{methoddesc}

\begin{methoddesc}[LinearPDE]{getSolution}{}
returns (an approximation of) the solution of the PDE. This call
will invoke the discretization of the PDE and the solution of the resulting
system of linear equations. Keep in mind that this call is typically computational 
expensive and can - depending on the PDE and the discretiztion - take a long time to complete. 
\end{methoddesc}


\subsection{The \Poisson Class}
The \Poisson class provides an easy way to define and solve the Poisson
equation
\begin{equation}\label{POISSON.1}
-u\hackscore{,ii}=f\; .
\end{equation}
with homogeneous boundary conditions
\begin{equation}\label{POISSON.2}
n\hackscore{i}u\hackscore{,i}=0
\end{equation}
and homogeneous constraints
\begin{equation}\label{POISSON.3}
u=0 \mbox{ where } q>0
\end{equation}
$f$ has to be a \Scalar in the \Function and $q$ must be
a \Scalar in  the \SolutionFS.

\begin{classdesc}{Poisson}{domain}
opens a Poisson equation on the \Domain domain. \Poisson is derived from \LinearPDE.
\end{classdesc}
\begin{methoddesc}[Poisson]{setValue}{f=escript.Data(),q=escript.Data()}
assigns new values to \var{f} and \var{q}.
\end{methoddesc}

\subsection{The \Helmholtz Class}
The \Helmholtz class defines the Helmholtz problem
\begin{equation}\label{HZ.1}
\omega \; u - (k\; u\hackscore{,j})\hackscore{,j} = f
\end{equation}
 with natural boundary conditions
\begin{equation}\label{HZ.2}
k\; u\hackscore{,j} n\hackscore{,j} = g- \alpha \; u 
\end{equation}
and constraints:
\begin{equation}\label{HZ.3}
u=r \mbox{ where } q>0
\end{equation}
$\omega$, $k$, $f$ have to be a \Scalar in the \Function,
$g$ and $\alpha$ must be a \Scalar in  the \FunctionOnBoundary,
and $q$ and $r$ must be a \Scalar in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.

\begin{classdesc}{Helmholtz}{domain}
opens a Helmholtz equation on the \Domain domain. \Helmholtz is derived from \LinearPDE.
\end{classdesc}
\begin{methoddesc}[Helmholtz]{setValue}{ \optional{omega} \optional{, k} \optional{, f} \optional{, alpha} \optional{, g} \optional{, r} \optional{, q}}
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.
\end{methoddesc}

\subsection{The \Lame Class}
The \Lame class defines a Lame equation problem:
\begin{equation}\label{LE.1}
-\mu (u\hackscore{i,j}+u\hackscore{j,i})+\lambda u\hackscore{k,k})\hackscore{j} = F\hackscore{i}-\sigma\hackscore{ij,j}
\end{equation}
with natural boundary conditions:
\begin{equation}\label{LE.2}
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}
\end{equation}
and constraint
\begin{equation}\label{LE.3}
u\hackscore{i}=r\hackscore{i} \mbox{ where } q\hackscore{i}>0
\end{equation}
$\mu$, $\lambda$ have to be a \Scalar in the \Function,
$F$ has to be a \Vector in the \Function,
$\sigma$ has to be a \Tensor in the \Function,
$f$ must be a \Vector in  the \FunctionOnBoundary,
and $q$ and $r$ must be a \Vector in  the \SolutionFS or must be mapped or interpolated into the particular \FunctionSpace.

\begin{classdesc}{Lame}{domain}
opens a Lame equation on the \Domain domain. \Lame is derived from \LinearPDE.
\end{classdesc}
\begin{methoddesc}[Lame]{setValue}{ \optional{lame_lambda} \optional{, lame_mu} \optional{, F} \optional{, sigma} \optional{, f} \optional{, r} \optional{, q}}
assigns new values to 
\var{lame_lambda},
\var{lame_mu},
\var{F},
\var{sigma},
\var{f},
\var{r} and
\var{q}
By default all values are set to be zero.
\end{methoddesc}

% \section{Transport Problems}
% \label{SEC Transport}

\section{Solver Options}
\label{SEC Solver Options}

\begin{classdesc}{SolverOptions}{}
This class defines the solver options for a linear or non-linear solver.
The option also supports the handling of diagnostic informations. 
\end{classdesc}

\begin{methoddesc}[SolverOptions]{getSummary}{}
Returns a string reporting the current settings
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getName}{key}
Returns the name as a string of a given key
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setSolverMethod}{\optional{method=SolverOptions.DEFAULT}}
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. 
The value of \var{method} must be one of the constants
 \member{SolverOptions.DEFAULT}, \member{SolverOptions.DIRECT}, \member{SolverOptions.CHOLEVSKY}, \member{SolverOptions.PCG},\member{SolverOptions.CR}, \member{SolverOptions.CGS}, \member{SolverOptions.BICGSTAB}, \member{SolverOptions.SSOR}, 
 \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}, 
 or \member{SolverOptions.GAUSS_SEIDEL}.
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.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getSolverMethod}{}
Returns key of the solver method to be used. 
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setPreconditioner}{\optional{preconditioner=SolverOptions.JACOBI}}
Sets the preconditioner to be used. 
The value of \var{preconditioner} must be one of the constants
\member{SolverOptions.SSOR}, \member{SolverOptions.ILU0}, \member{SolverOptions.ILUT}, \member{SolverOptions.JACOBI}, 
\member{SolverOptions.AMG}, \member{SolverOptions.REC_ILU}, \member{SolverOptions.GAUSS_SEIDEL}, \member{SolverOptions.RILU}, or
\member{SolverOptions.NO_PRECONDITIONER}.
Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters
an unknown preconditioner. See Table~\ref{TAB FINLEY SOLVER OPTIONS 2} for the solvers supported by \finley.
\end{methoddesc}
   
\begin{methoddesc}[SolverOptions]{getPreconditioner}{}
Returns key of the preconditioner to be used. 
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setPackage}{\optional{package=SolverOptions.DEFAULT}}
Sets the solver package to be used as a solver.  
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}.
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)
and, if available, \member{SolverOptions.MKL} and \member{SolverOptions.UMFPACK}.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getPackage}{}
Returns the solver package key
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{resetDiagnostics}{\optional{all=False}}
resets the diagnostics. If \var{all} is \True all diagnostics including accumulative counters are reset.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getDiagnostics}{\optional{ name}}
Returns the diagnostic information \var{name}. The following keywords are
supported:
\begin{itemize}
 \item "num_iter": the number of iteration steps
 \item "cum_num_iter": the cumulative number of iteration steps
 \item "num_level": the number of level in multi level solver
 \item "num_inner_iter": the number of inner iteration steps
 \item"cum_num_inner_iter": the cumulative number of inner iteration steps
 \item"time": execution time 
 \item "cum_time": cumulative execution time
 \item "set_up_time": time to set up of the solver, typically this includes factorization and reordering
 \item "cum_set_up_time": cumulative time to set up of the solver
 \item "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner
 \item "cum_net_time": cumulative net execution time
 \item "residual_norm": norm of the final residual
 \item "converged": return self.__converged     
\end{itemize}
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{hasConverged}{}
Returns \True if the last solver call has been finalized successfully.
If an exception has been thrown by the solver the status of this flag is undefined.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setCoarsening}{\optional{method=SolverOptions.DEFAULT}}
Sets the key of the coarsening method to be applied in \AMG.
The value of \var{method} must be one of the constants
\member{SolverOptions.DEFAULT}
\member{SolverOptions.YAIR_SHAPIRA_COARSENING}, \\
\member{SolverOptions.RUGE_STUEBEN_COARSENING}, \\or \member{SolverOptions.AGGREGATION_COARSENING}.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getCoarsening}{}
Returns the key of the coarsening algorithm to be applied \AMG.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setReordering}{\optional{ordering=SolverOptions.DEFAULT_REORDERING}}
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
 \member{SolverOptions.NO_REORDERING}, \member{SolverOptions.MINIMUM_FILL_IN}, 
        \member{SolverOptions.NESTED_DISSECTION}, or \member{SolverOptions.DEFAULT_REORDERING}.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getReordering}{}
Returns the key of the reordering method to be applied if supported by the solver.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setRestart}{\optional{restart=None}}
Sets the number of iterations steps after which \GMRES is performing a restart.
If \var{restart} is equal to \var{None} no restart is performed.
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{getRestart}{}
Returns the number of iterations steps after which \GMRES is performing a restart.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setTruncation}{\optional{truncation=20}}
Sets the number of residuals in \GMRES to be stored for orthogonalization.  The more residuals are stored the faster \GMRES converged but
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getTruncation}{}
Returns the number of residuals in \GMRES to be stored for orthogonalization
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{setIterMax}{\optional{iter_max=10000}}
Sets the maximum number of iteration steps
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getIterMax}{}
Returns maximum number of iteration steps
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setLevelMax}{\optional{level_max=10}}
Sets the maximum number of coarsening levels to be used in the \AMG solver or preconditioner.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getLevelMax}{}
Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setCoarseningThreshold}{\optional{theta=0.05}}
Sets the threshold for coarsening in the \AMG solver or preconditioner
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getCoarseningThreshold}{}
Returns the threshold for coarsening in the \AMG solver or preconditioner
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setMinCoarseMatrixSize}{\optional{size=500}}
Sets the minumum size of the coarsest level matrix in AMG.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getMinCoarseMatrixSize}{}
Returns the minumum size of the coarsest level matrix in AMG.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setNumSweeps}{\optional{sweeps=2}}
Sets the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getNumSweeps}{}
Returns the number of sweeps in a \JACOBI or \GAUSSSEIDEL preconditioner.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setNumPreSweeps}{\optional{sweeps=2}}
Sets the number of sweeps in the pre-smoothing step of \AMG
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getNumPreSweeps}{}
Returns the number of sweeps in the pre-smoothing step of \AMG
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setNumPostSweeps}{\optional{sweeps=2}}
Sets the number of sweeps in the post-smoothing step of \AMG
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getNumPostSweeps}{}
Returns he number of sweeps sweeps in the post-smoothing step of \AMG
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setTolerance}{\optional{rtol=1.e-8}}
Sets the relative tolerance for the solver. The actually meaning of tolerance depends 
on the underlying PDE library. In most cases, the tolerance
will only consider the error from solving the discrete problem but will
not consider any discretization error.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getTolerance}{}
Returns the relative tolerance for the solver
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setAbsoluteTolerance}{\optional{atol=0.}}
Sets the absolute tolerance for the solver. The actually meaning of tolerance depends 
on the underlying PDE library. In most cases, the tolerance
will only consider the error from solving the discrete problem but will
not consider any discretization error.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getAbsoluteTolerance}{}
Returns the absolute tolerance for the solver
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{setInnerTolerance}{\optional{rtol=0.9}}
Sets the relative tolerance for an inner iteration scheme for instance
on the coarsest level in a multi-level scheme.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getInnerTolerance}{}
Returns the relative tolerance for an inner iteration scheme
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setDropTolerance}{\optional{drop_tol=0.01}}
Sets the relative drop tolerance in ILUT
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getDropTolerance}{}
Returns the relative drop tolerance in \ILUT
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{setDropStorage}{\optional{storage=2.}}
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.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getDropStorage}{}
Returns the maximum allowed increase in storage for \ILUT
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setRelaxationFactor}{\optional{factor=0.3}}
Sets the relaxation factor used to add dropped elements in \RILU to the main diagonal.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getRelaxationFactor}{}
Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{isSymmetric}{}
Returns \True is the descrete system is indicated as symmetric.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setSymmetryOn}{}
Sets the symmetry flag to indicate that the coefficient matrix is symmetric.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setSymmetryOff}{}
Clears the symmetry flag for the coefficient matrix.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{isVerbose}{}
 Returns \True if the solver is expected to be verbose.
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{setVerbosityOn}{}
Switches the verbosity of the solver on.
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{setVerbosityOff}{}
Switches the verbosity of the solver off.
\end{methoddesc}


\begin{methoddesc}[SolverOptions]{adaptInnerTolerance}{}
Returns \True if the tolerance of the inner solver is selected automatically. 
Otherwise the inner tolerance set by \member{setInnerTolerance} is used.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOn}{}
Switches the automatic selection of inner tolerance on 
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setInnerToleranceAdaptionOff}{}
Switches the automatic selection of inner tolerance off.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setInnerIterMax}{\optional{iter_max=10}}
Sets the maximum number of iteration steps for the inner iteration.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{getInnerIterMax}{}
Returns maximum number of inner iteration steps.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{acceptConvergenceFailure}{}
Returns \True if a failure to meet the stopping criteria within the
given number of iteration steps is not raising in exception. This is useful 
if a solver is used in a non-linear context where the non-linear solver can 
continue even if the returned the solution does not necessarily meet the
stopping criteria. One can use the \member{hasConverged} method to check if the
last call to the solver was successful.
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOn}{}
Switches the acceptance of a failure of convergence on.  
\end{methoddesc}

\begin{methoddesc}[SolverOptions]{setAcceptanceConvergenceFailureOff}{}
Switches the acceptance of a failure of convergence off.
\end{methoddesc}
    
\begin{memberdesc}[SolverOptions]{DEFAULT}
default method, preconditioner or package to be used to solve the PDE. An appropriate method should be
chosen by the used PDE solver library.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{MKL}
the \MKL library by Intel,~\Ref{MKL}\footnote{The \MKL library will only be available when the Intel compilation environment is used.}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{UMFPACK}
the \UMFPACK,~\Ref{UMFPACK}. Remark: \UMFPACK is not parallelized.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{PASO}
\PASO is the solver library of \finley, see \Sec{CHAPTER ON FINLEY}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{ITERATIVE}
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.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{DIRECT}
the default direct linear solver.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{CHOLEVSKY}
direct solver based on Cholevsky factorization (or similar), see~\Ref{Saad}. The solver will require a symmetric PDE.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{PCG}
preconditioned conjugate gradient method, see~\Ref{WEISS}\index{linear solver!PCG}\index{PCG}. The solver will require a symmetric PDE.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{TFQMR}
transpose-free quasi-minimal residual method, see~\Ref{WEISS}\index{linear solver!TFQMR}\index{TFQMR}. \end{memberdesc}

\begin{memberdesc}[SolverOptions]{GMRES}
the GMRES method, see~\Ref{WEISS}\index{linear solver!GMRES}\index{GMRES}. Truncation and restart are controlled by the parameters
\var{truncation} and \var{restart} of \method{getSolution}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{MINRES}
minimal residual method method, \index{linear solver!MINRES}\index{MINRES} \end{memberdesc}

\begin{memberdesc}[SolverOptions]{LUMPING}
uses lumping to solve the system of linear equations~\index{linear solver!lumping}\index{lumping}. This solver technique
condenses the stiffness matrix to a diagonal matrix so the solution of the linear systems becomes very cheap. It can be used when
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
but is expected to converge to zero when the mesh gets finer.
Lumping does not use the linear system solver library.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{PRES20}
the GMRES method with truncation after five residuals and
restart after 20 steps, see~\Ref{WEISS}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{CGS}
conjugate gradient squared method, see~\Ref{WEISS}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{BICGSTAB}
stabilized bi-conjugate gradients methods, see~\Ref{WEISS}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{SSOR}
symmetric successive over-relaxation method, see~\Ref{WEISS}. Typically used as preconditioner but some linear solver libraries support
this as a solver.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{ILU0}
the incomplete LU factorization preconditioner with no fill-in, see~\Ref{Saad}.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{ILUT}
the incomplete LU factorization preconditioner with fill-in, see~\Ref{Saad}. During the  LU-factorization element with
relative size less then \member{getDropTolerance} are dropped. Moreover, the size of the LU-factorization is restricted to the
\member{getDropStorage}-fold of the stiffness matrix. \member{getDropTolerance} and \member{getDropStorage} are both set in the
\method{getSolution} call.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{JACOBI}
the Jacobi preconditioner, see~\Ref{Saad}.
\end{memberdesc}


\begin{memberdesc}[SolverOptions]{AMG}
the algebraic--multi grid method, see~\Ref{AMG}. This method can be used as linear solver method but is more robust when used
in a preconditioner.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{GAUSS_SEIDEL}
the symmetric Gauss-Seidel preconditioner, see~\Ref{Saad}.
\member{getNumSweeps()} is the number of sweeps used.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{RILU}
relaxed incomplete LU factorization preconditioner, see~\Ref{RELAXILU}. This method is similar to \ILU0 but dropped elements are added to the main diagonal 
with the relaxation factor \member{getRelaxationFactor}
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{REC_ILU}
recursive incomplete LU factorization preconditioner, see~\Ref{RILU}. This method is similar to \ILU0 but applies reordering during the factorization.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{NO_REORDERING}
no ordering is used during factorization.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{DEFAULT_REORDERING}
the default reordering method during factorization.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{MINIMUM_FILL_IN}
applies reordering before factorization using a fill-in minimization strategy. You have to check with the particular solver library or
linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{NESTED_DISSECTION}
applies reordering before factorization using a nested dissection strategy. You have to check with the particular solver library or
linear solver package if this is supported. In any case, it is advisable to apply reordering on the mesh to minimize fill-in.
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{TRILINOS}
the Trilinos library is used as a solver~\Ref{TRILINOS}
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{SUPER_LU}
the SuperLU library is used as a solver~\Ref{SuperLU}
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{PASTIX}
the Pastix library is used as a solver~\Ref{PASTIX}
\end{memberdesc}


\begin{memberdesc}[SolverOptions]{YAIR_SHAPIRA_COARSENING}
\AMG coarsening method by Yair-Shapira
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{RUGE_STUEBEN_COARSENING} \AMG coarsening method by Ruge and Stueben
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{AGGREGATION_COARSENING} \AMG coarsening using (symmetric) aggregation 
\end{memberdesc}

\begin{memberdesc}[SolverOptions]{NO_PRECONDITIONER}
no preconditioner is applied.
\end{memberdesc}

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