\section{Conditions}
This section of the file defines parameters and boundary conditions which
define the nature of the problem to be solved. These are enclosed in the
\inltt{CONDITIONS} tag.

\subsection{Parameters}

Numerical parameters may be required by a particular solver (for instance time-integration or physical parameters), or may be arbitrary and only used for the purpose of simplifying the problem specification in the session file (e.g. parameters which would otherwise be repeated in the definition of an initial
condition and boundary conditions). All parameters are enclosed in the \inltt{PARAMETERS} XML element.

\begin{lstlisting}[style=XMLStyle] 
<PARAMETERS>
    ...
</PARAMETERS>
\end{lstlisting}

A parameter may be of integer or real type and may reference other parameters
defined previous to it. It is expressed in the file as

\begin{lstlisting}[style=XMLStyle]
<P> [PARAMETER NAME] = [PARAMETER VALUE] </P>
\end{lstlisting}

For example,

\begin{lstlisting}[style=XMLStyle]
<P> NumSteps = 1000              </P>
<P> TimeStep = 0.01              </P>
<P> FinTime  = NumSteps*TimeStep </P>
\end{lstlisting}

A number of pre-defined constants may also be used in parameter expressions, for example \texttt{PI}. A full list of supported constants is provided in Section~\ref{sec:xml:expressions:syntax}.

\subsection{Time Integration Scheme}

These specify properties to define the parameters specific to the time
integration scheme to be used. The parameters are specified as XML
elements and require a string corresponding to the time-stepping method
and the order, and optionally the variant and free parameters. For
example,

\begin{lstlisting}[style=XMLStyle]
 <TIMEINTEGRATIONSCHEME>
   <METHOD> IMEX </METHOD>
   <VARIANT> DIRK </VARIANT>
   <ORDER> 2 </ORDER>
   <FREEPARAMETERS> 2 3 </FREEPARAMETERS>
 </TIMEINTEGRATIONSCHEME>
\end{lstlisting}

For additional details on the different time integration schemes refer
to the developer's guide.

\subsection{Solver Information}

These specify properties to define the actions specific to solvers,
typically including the equation to solve and the projection type. The
property/value pairs are specified as XML attributes. For example,

\begin{lstlisting}[style=XMLStyle] 
<SOLVERINFO>
  <I PROPERTY="EQTYPE"                VALUE="UnsteadyAdvection"    /> 
  <I PROPERTY="Projection"            VALUE="Continuous"           /> 
</SOLVERINFO>
\end{lstlisting}

Boolean-valued solver properties are specified using \inltt{True} or \inltt{False}. The list of available solvers in Nektar++ can be found in
Part~\ref{p:applications}.

\subsubsection{Drivers}
Drivers are defined under the \inltt{CONDITIONS} section as properties of the 
\inltt{SOLVERINFO} XML element. The role of a driver is to manage the solver 
execution from an upper level. 

The default driver is called \inltt{Standard} and executes the following steps:
\begin{enumerate}
\item Prints out on screen a summary of all the conditions defined in the input file.
\item Sets up the initial and boundary conditions.
\item Calls the solver defined by \inltt{SolverType}  in the \inltt{SOLVERINFO} XML element.
\item Writes the results in the output (.fld) file.
\end{enumerate}

In the following example, the driver \inltt{Standard} is used to manage the 
execution of the incompressible Navier-Stokes equations:
\begin{lstlisting}[style=XMLStyle]
 <TIMEINTEGRATIONSCHEME>
    <METHOD> IMEX </METHOD>
    <ORDER> 2 </ORDER>
 </TIMEINTEGRATIONSCHEME>

 <SOLVERINFO>
    <I PROPERTY="EQTYPE"                VALUE="UnsteadyNavierStokes"     />
    <I PROPERTY="SolverType"            VALUE="VelocityCorrectionScheme" />
    <I PROPERTY="Projection"            VALUE="Galerkin"                 />
    <I PROPERTY="Driver"                VALUE="Standard"                 />
</SOLVERINFO>
\end{lstlisting}

If no driver is specified in the session file, the driver \inltt{Standard} is 
called by default. Other drivers can be used and are typically focused on
specific applications. As described in Sec.
\ref{SectionIncNS_SolverInfo} and  \ref{SectionIncNS_SolverInfo_Stab}, 
the other possibilities are:
\begin{itemize}
\item \inltt{ModifiedArnoldi}  - computes of the leading eigenvalues and 
eigenmodes using modified Arnoldi method.
\item \inltt{Arpack} - computes of eigenvalues/eigenmodes using Implicitly 
Restarted Arnoldi Method (ARPACK).
\item \inltt{SteadyState} - uses the Selective Frequency Damping method 
(see Sec. \ref{SectionSFD}) to obtain a steady-state solution of the 
Navier-Stokes equations (compressible or incompressible).
\end{itemize}

\subsection{Variables}

These define the number (and name) of solution variables. Each variable is
prescribed a unique ID. For example a two-dimensional flow simulation may define
the velocity variables using

\begin{lstlisting}[style=XMLStyle]
<VARIABLES>
  <V ID="0"> u </V>
  <V ID="1"> v </V>
</VARIABLES>
\end{lstlisting}

\subsection{Global System Solution Algorithm}
\label{globalsyssoln}
Many \nekpp solvers use an implicit formulation of their equations to, for
instance, improve timestep restrictions. This means that a large matrix system
must be constructed and a global system set up to solve for the unknown
coefficients. There are several approaches in the spectral/$hp$ element method
that can be used in order to improve efficiency in these methods, as well as
considerations as to whether the simulation is run in parallel or serial. \nekpp
opts for `sensible' default choices, but these may or may not be optimal
depending on the problem under consideration.

This section of the XML file therefore allows the user to specify the global
system solution parameters, which dictates the type of solver to be used for any
implicit systems that are constructed. This section is particularly useful when
using a multi-variable solver such as the incompressible Navier-Stokes solver,
as it allows us to select different preconditioning and residual convergence
options for each variable. As an example, consider the block defined by:

\begin{lstlisting}[style=XMLStyle]
<GLOBALSYSSOLNINFO>
  <V VAR="u,v,w">
    <I PROPERTY="GlobalSysSoln"             VALUE="IterativeStaticCond" />
    <I PROPERTY="Preconditioner"            VALUE="LowEnergyBlock"/>
    <I PROPERTY="IterativeSolverTolerance"  VALUE="1e-8"/>
  </V>
  <V VAR="p">
    <I PROPERTY="GlobalSysSoln"             VALUE="IterativeStaticCond" />
    <I PROPERTY="Preconditioner"     VALUE="FullLinearSpaceWithLowEnergyBlock"/>
    <I PROPERTY="IterativeSolverTolerance"  VALUE="1e-6"/>
  </V>
</GLOBALSYSSOLNINFO>
\end{lstlisting}

The above section specifies that the variables \texttt{u,v,w} should use the
\texttt{IterativeStaticCond} global solver alongside the \texttt{LowEnergyBlock}
preconditioner and an iterative tolerance of $10^{-8}$ on the residuals. However
the pressure variable \texttt{p} is generally stiffer: we therefore opt for a
more expensive \texttt{FullLinearSpaceWithLowEnergyBlock} preconditioner and a
larger residual of $10^{-6}$. We now outline the choices that one can use for
each of these parameters and give a brief description of what they mean.

By default, iterative linear solvers uses a relative tolerance specified in the
above exmaple. Setting the property \texttt{<I PROPERTY="AbsoluteTolerance" VALUE="True">}
will override the default and force the solver to use the absolute tolerance.
Note that the value of tolerance is still
controlled by setting \texttt{<I PROPERTY=IterativeSolverTolerance" VALUE="1.e-8"/>}
and if not set the default tolerance will be used.

Defaults for all fields can be defined by setting the equivalent property in
the \texttt{SOLVERINFO} section. Parameters defined in this section will
override any options specified there.


\subsubsection{\texttt{GlobalSysSoln} options}

\nekpp presently implements four methods of solving a global system:

\begin{itemize}
  \item \textbf{Direct} solvers construct the full global matrix and directly
  invert it using an appropriate matrix technique, such as Cholesky
  factorisation, depending on the properties of the matrix. Direct solvers
  \textbf{only} run in serial.
  \item \textbf{Iterative} solvers instead apply matrix-vector multiplications
  repeatedly, using the conjugate gradient method, to converge to a solution to
  the system. For smaller problems, this is typically slower than a direct
  solve. However, for larger problems it can be used to solve the system in
  parallel execution.
  \item \textbf{Xxt} solvers use the $XX^T$ library to perform a parallel direct
  solve. This option is only available if the \texttt{NEKTAR\_USE\_MPI} option
  is enabled in the CMake configuration.
  \item \textbf{PETSc} solvers use the PETSc library, giving access to a wide
  range of solvers and preconditioners. See section~\ref{sec:petsc} below for
  some additional information on how to use the PETSc solvers. This option is
  only available if the \texttt{NEKTAR\_USE\_PETSC} option is enabled in the
  CMake configuration.
\end{itemize}

\begin{warningbox}
Both the \textbf{Xxt} and \textbf{PETSc} solvers are considered advanced and are
under development -- either the direct or iterative solvers are recommended in
most scenarios.
\end{warningbox}

These solvers can be run in one of three approaches:

\begin{itemize}
  \item The \textbf{Full} approach constructs the global system based on all of
  the degrees of freedom contained within an element. For most of the \nekpp
  solvers, this technique is not recommended.
  \item The \textbf{StaticCond} approach applies a technique called \emph{static
    condensation} to instead construct the system using only the degrees of
  freedom on the boundaries of the elements, which reduces the system size
  considerably. This is the \textbf{default option in parallel}.
  \item \textbf{MultiLevelStaticCond} methods apply the static condensation
  technique repeatedly to further reduce the system size, which can improve
  performance by 25-30\% over the normal static condensation method. It is
  therefore the \textbf{default option in serial}. Note that whilst parallel
  execution technically works, this is under development and is likely to be
  slower than single-level static condensation: this is therefore not
  recommended.
\end{itemize}

The \texttt{GlobalSysSoln} option is formed by combining the method of solution
with the approach: for example \texttt{IterativeStaticCond} or
\texttt{PETScMultiLevelStaticCond}.

\subsubsection{Iterative  options}
\begin{itemize}
\item \textbf{LinSysIterSolver} which specifies which iterative solver
  strategy to use and includes values of \textbf{ConjugateGradient} or
  \textbf{GMRES}. The default option is to solve this in a global
  degree of freedom array for continuous Galerkin discretisations but
  there are also options of \textbf{ConjugateGradientLoc} and
  \textbf{GMRESLoc} which solve the array in local element format. For
  DG discretisations these should be the same.
\item \textbf{NekLinSysMaxIterations} specifies the maximum number of
  iterations and has a default value of 5000.
\item \textbf{IterativeSolverTolerance} specifies the relative
  stopping tolerances for the iterative solver. Default is $1e-9$.
\item \textbf{FlexibleConjugateGradient} specifies if Flexible version of 
  ConjugateGradient is used. Possible values are 1 or 0 (Default is 0). 
  The "Flexible" variant of the ConjugateGradient algorithm relaxes some 
  restriction regarding the preconditioner (constant SPD).
\item \textbf{FlexibleGMRES} specifies if Flexible version of GMRES is used. 
  Possible values are 1 or 0 (Default is 0). The "Flexible" variant of the 
  GMRES algorithm allows the use of a non-linear preconditioner. The required
  memory storage is about the double of regular GMRES.
\item \textbf{GMRESDeltaDirection} specifies number of vector to carry between
  GMRES restart cycle to improve convergence of restarted GMRES (LGMRES). Recommended
  number of GMRESDeltaDirection is between 1 and 3 (Default is 0). 
\item \textbf{EvsDirect} does not solve the linear system but computes the preconditioned matrix $M^{-1}A$ and the eigenvalues via \verb!lapack::Dgeev!. Both are written into Matrix.txt" and "Eigenvalues.txt", respectively, inside the current working directory. Note that this method is only tested for a \textbf{Full} matrix system and is not working in parallel, hence, only for problem sizes. See the table below for Preconditioner options.
\end{itemize} 

\subsubsection{Preconditioner options}

Preconditioners can be used in the iterative and PETSc solvers to reduce the
number of iterations needed to converge to the solution. There are a number of
preconditioner choices, the default being a simple Jacobi (or diagonal)
preconditioner, which is enabled by default. There are a number of choices that
can be enabled through this parameter, which are all generally discretisation
and dimension-dependent:

\begin{center}
  \begin{tabular}{lll}
    \toprule
    \textbf{Name}  & \textbf{Dimensions} & \textbf{Discretisations} \\
    \midrule
    \inltt{Null}                              & All  & All \\
    \inltt{Diagonal}                          & All  & All \\
    \inltt{FullLinearSpace}                   & 2/3D & CG  \\
    \inltt{Jacobi}                            & 2/3D & All  \\
    \inltt{LowEnergyBlock}                    & 3D   & CG  \\
    \inltt{Block}                             & 2/3D & All \\
    \inltt{LOR}                               & 2/3D & CG \\
    \midrule
    \inltt{FullLinearSpaceWithDiagonal}       & All  & CG  \\
    \inltt{FullLinearSpaceWithLowEnergyBlock} & 2/3D & CG  \\
    \inltt{FullLinearSpaceWithBlock}          & 2/3D & CG  \\
    \bottomrule
  \end{tabular}
\end{center}

For a detailed discussion of the mathematical formulation of these options, see
the developer guide.

\subsubsection{SuccessiveRHS options}

The \texttt{SuccessiveRHS} option can be used in the iterative solver only, to
attempt to reduce the number of iterations taken to converge to a solution. It
stores a number of previous solutions or right-hand sides, dictated by the setting of the
\texttt{SuccessiveRHS} option, to give a better initial guess for the iterative
process. This  method is better than any linear extrapolation method.

It can be activated by setting
\begin{lstlisting}[style=XMLStyle]
<GLOBALSYSSOLNINFO>
    <V VAR="u,v,w">
        <I PROPERTY="GlobalSysSoln"         VALUE="IterativeStaticCond" />
        <I PROPERTY="Preconditioner"       VALUE="LowEnergyBlock"/>
        <I PROPERTY="SuccessiveRHS"       VALUE="8" />
        <I PROPERTY="IterativeSolverTolerance"    VALUE="1e-4"/>
    </V>
    <V VAR="p">
        <I PROPERTY="GlobalSysSoln"           VALUE="IterativeStaticCond" />
        <I PROPERTY="Preconditioner"         VALUE="LowEnergyBlock"/>
        <I PROPERTY="SuccessiveRHS"         VALUE="8" />
        <I PROPERTY="IterativeSolverTolerance"    VALUE="1e-4"/>
    </V>
</GLOBALSYSSOLNINFO>
\end{lstlisting}
or
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> SuccessiveRHS = 8 </P>
</PARAMETERS>
\end{lstlisting}
The typical value of \texttt{SuccessiveRHS} is $\le$10.

The linear problem to be solved is
\begin{equation}\label{eq:linearEquationNew}
A x = b,
\end{equation}
here $x$ and $b$ are both column vectors.
There are a sequence of  already solved linear problems
\begin{equation}\label{eq:linearEquationOld}
A x_n = b_n, n = 1, 2, ..., J.
\end{equation}
Assume $x_n$ are all linearly independent.
In the successive right-hand method (see \cite{FISCHER1998193}), the best approximation to $x$ is
\begin{equation}\label{eq:approximate}
\tilde{x}=\sum_{n=1}^J\alpha_n x_n
\end{equation}
which is found by minimizing the object function
\begin{equation}\label{eq:objectFunction1}
Q_1 = \left(A(\tilde{x}-x)\right)^TA(\tilde{x}-x),
\end{equation}
or
\begin{equation}\label{eq:objectFunction2}
Q_2 = (\tilde{x}-x)^TA(\tilde{x}-x).
\end{equation}

If $Q_1$ is used, the projection bases are $e_m = b_m, m = 1, 2, ..., J$. Using
\begin{equation}\label{eq:Atildex}
\left(A(\tilde{x}-x) \right)^T= \sum_{m=1}^J\alpha_me_m^T - b^T,
\end{equation}
there is
\begin{equation}\label{eq:objectFunctionQ1_v2}
Q_1= \sum_{m=1}^J\sum_{n=1}^J\alpha_m\alpha_n e_m^T b_n - 2 \sum_{m=1}^J \alpha_m e_m^T b + b^T b.
\end{equation}
To minimize $Q_1$, there should be $\partial Q_1/\partial \alpha_m =0, m=1, 2, ..., J$.
The corresponding linear problem is
\begin{equation}\label{eq:objectFunctionQ1_solution}
M (\alpha_1, \alpha_2, ..., \alpha_J)^T =   (e_1^Tb, e_2^Tb, ..., e_J^Tb)^T,
\end{equation}
with symmetric positive definite coefficient matrix $M_{mn}=e_m^T b_n$. In this case, both the solutions $x_m$ and the right-hand sides $b_m$ need to be stored.

If $Q_2$ is used, $A$ should be a symmetric positive definite matrix, as those encountered in the Poisson equation and the Helmholtz equation. Here, the projection bases are $\hat{e}_m = x_m, m = 1, 2, ..., J$. Using
\begin{equation}\label{eq:tildex}
(\tilde{x}-x) ^T= \sum_{m=1}^J\alpha_n\hat{e}_m^T - x^T,
\end{equation}
there is
\begin{equation}\label{eq:objectFunctionQ2_v2}
Q_2= \sum_{m=1}^J\sum_{n=1}^J\alpha_m\alpha_n \hat{e}_m^T b_n - 2 \sum_{m=1}^J \alpha_m \hat{e}_m^T b + x^T b.
\end{equation}
To minimize $Q_2$, there should be $\partial Q_2/\partial \alpha_m =0, m=1, 2, ..., J$.
The corresponding linear problem is
\begin{equation}\label{eq:objectFunctionQ2_solution}
M (\alpha_1, \alpha_2, ..., \alpha_J)^T =   (\hat{e}_1^Tb, \hat{e}_2^Tb, ..., \hat{e}_J^Tb)^T,
\end{equation}
with symmetric positive definite coefficient matrix $M_{mn}=\hat{e}_m^T b_n$. In this case, only the solutions $x_m$ need to be stored.

The formulations of $Q_1$ version and $Q_2$ version are the same, except the difference of projection bases. By default, $Q_2$ is used as the object function. If you want to use $Q_1$ instead, you can assign a negative value to \texttt{SuccessiveRHS}:
\begin{lstlisting}[style=XMLStyle]
<I PROPERTY="SuccessiveRHS"         VALUE="-8" />
\end{lstlisting}
or
\begin{lstlisting}[style=XMLStyle]
<P> SuccessiveRHS = -8 </P>
\end{lstlisting}

In the original paper of Fischer (1998) \cite{FISCHER1998193}, the Gram-Schmidt orthogonal process is applied to the projection bases, this method is very stable and avoids the calculation of $M^{-1}$. However, when the memory space is full, this approach makes it hard to decide which basis should be overwritten. In our implementation, we just store the normalized right-hand sides or old solutions, i.e. $e_m^T b_m=1$ or $\hat{e}_m^T b_m=1$, and overwrite the oldest ones. The linear problem (\ref{eq:objectFunctionQ1_solution}) or (\ref{eq:objectFunctionQ2_solution}) is solved using a direct method.

To make sure $M$ is positive definite, when a new basis $e_{J+1}$ arrives, we test the following condition to decide whether or not to accept it,
\begin{equation}\label{eq:thredhold}
r = (-y^T\tilde{M} ^{-1}, 1) \begin{pmatrix}
\tilde{M}     & y\\
y^T  & 1
\end{pmatrix}
\begin{pmatrix}
-\tilde{M} ^{-1}y\\
1
\end{pmatrix} =1 - y^T\tilde{M}^{-1}y \ge \varepsilon > 0.
\end{equation}
Assuming $e_J$ is the oldest basis, there are $\tilde{M}_{mn} = M_{mn}, y_m = e_{m}^Tb_{J+1}, (m, n=1, 2, ..., J-1)$.

\subsubsection{PETSc options and configuration}
\label{sec:petsc}

The PETSc solvers, although currently experimental, are operational both in
serial and parallel. PETSc gives access to a wide range of alternative solver
options such as GMRES, as well as any packages that PETSc can link against, such
as the direct multi-frontal solver MUMPS.

Configuration of PETSc options using its command-line interface dictates what
matrix storage, solver type and preconditioner should be used. This should be
specified in a \texttt{.petscrc} file inside your working directory, as command
line options are not currently passed through to PETSc to avoid conflict with
\nekpp options. As an example, to select a GMRES solver using an algebraic
multigrid preconditioner, and view the residual convergence, one can use the
configuration:

\begin{lstlisting}[style=BashInputStyle]
-ksp_monitor
-ksp_view
-ksp_type gmres
-pc_type gamg
\end{lstlisting}

Or to use MUMPS, one could use the options:

\begin{lstlisting}[style=BashInputStyle]
-ksp_type preonly
-pc_type lu
-pc_factor_mat_solver_package mumps
-mat_mumps_icntl_7 2
\end{lstlisting}

A final choice that can be specified is whether to use a \emph{shell}
approach. By default, \nekpp will construct a PETSc sparse matrix (or whatever
matrix is specified on the command line). This may, however, prove suboptimal
for higher order discretisations. In this case, you may choose to use the \nekpp
matrix-vector operators, which by default use an assembly approach that can
prove faster, by setting the \texttt{PETScMatMult} \texttt{SOLVERINFO} option to
\texttt{Shell}:

\begin{lstlisting}[style=XMLStyle]
<I PROPERTY="PETScMatMult" VALUE="Shell" />
\end{lstlisting}

The downside to this approach is that you are now constrained to using one of
the \nekpp preconditioners. However, this does give access to a wider range of
Krylov methods than are available inside \nekpp for more advanced users.

\subsection{Nonlinear Newton solver options}

Many problems require the solution of a nonlinear system of equations
$$
    F(u) = 0,
$$
where $u$ denotes the solution vector and $F(u)$ is the nonlinear
residual. The Newton iterative method linearises the solution process such that
at nonlinear iteration $k$,
a correction $\delta_k$ results from the linearised system
$$
    J(u_k)\delta_k = F(u_k),
$$
where $J(u_k)$ is the Jacobian of $F$ at $u_k$.

Iteratively updating $u_k$ with the correction $\delta_k$ the Newton iteration step is then
$$
    u_{k+1} = u_k - \delta_k.
$$

Often, the computed correction $\delta_k$ is too aggressive or does not represent
the nonlinear problem well.
Below, we list several options and techniques to stabilise the Newton iterative process.

\subsubsection{Vanilla Newton}

The default nonlinear solver is the standard Newton method. It applies the
computed Newton correction directly, unless a fixed Newton scale is specified.

To select it explicitly in the \inltt{SOLVERINFO} tag, use
\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
    <I PROPERTY="NonlinearSolver" VALUE="Newton" />
</SOLVERINFO>
\end{lstlisting}

The relevant default parameters are
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> LinSysRelativeTolInNonlin = 1.0e-6 </P>
    <P> NewtonScale               = 1.0    </P>
</PARAMETERS>
\end{lstlisting}

Here \inltt{LinSysRelativeTolInNonlin} defines the relative tolerance used for
the linear solve inside Newton when inexact Newton forcing is disabled.

\subsubsection{Inexact Newton forcing}

Inexact Newton forcing changes the accuracy requested from the linear solver at
each nonlinear iteration. Instead of solving the Newton correction to a fixed
relative tolerance, the linear solve is stopped when
$$
    \|J(u_k)\delta_k - F(u_k)\|_2
    \leq \eta_k \|F(u_k)\|_2.
$$
If inexact forcing is enabled, the forcing parameter is chosen as
$$
    \eta_0 = \eta_{\mathrm{init}},
$$
and for $k>0$,
$$
    \eta_k =
    \min\left(
        \eta_{\max},
        \max\left(
            \eta_{\min},
            \gamma
            \left(
                \frac{\|F(u_k)\|_2}{\|F(u_{k-1})\|_2}
            \right)^\alpha
        \right)
    \right).
$$
This reduces unnecessary linear iterations far from convergence, while allowing
a tighter linear solve as the nonlinear residual decreases.

To activate the inexact forcing, no additional \inltt{SOLVERINFO} option is required. The forcing parameters are
common to the Newton-based nonlinear solvers:
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> InexactNewtonForcing     = 0      </P>
    <P> LinSysRelativeTolInNonlin = 1.0e-6 </P>
    <P> ForcingEtaInit           = 1.0e-2 </P>
    <P> ForcingEtaMin            = 1.0e-6 </P>
    <P> ForcingEtaMax            = 5.0e-2 </P>
    <P> ForcingGamma             = 0.9    </P>
    <P> ForcingAlpha             = 1.5    </P>
</PARAMETERS>
\end{lstlisting}

By default \inltt{InexactNewtonForcing} is disabled ($0$). To turn it on set \inltt{InexactNewtonForcing     = 1 }. If
\inltt{ForcingEtaMin} is not specified, the value is copied from
\inltt{LinSysRelativeTolInNonlin}.

\subsubsection{Fixed Newton scale}

A simple stabilisation technique is to apply a fixed fraction of the Newton correction.
The Newton update then becomes
$$
    u_{k+1} = u_k - \alpha \delta_k,
$$
where $\alpha$ is specified by \inltt{NewtonScale}. The default value
$\alpha=1$ gives the full Newton step.

This option uses the standard Newton solver:
\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
    <I PROPERTY="NonlinearSolver" VALUE="Newton" />
</SOLVERINFO>
\end{lstlisting}

The parameter is set in the \inltt{PARAMETERS} tag as
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> NewtonScale = 0.1 </P>
</PARAMETERS>
\end{lstlisting}

The stabilising effect results from taking much shorter steps along the computed correction $\delta_k$.

\subsubsection{Backtracking}

The backtracking solver applies the Newton correction with an adaptive scale
$\alpha$. For a trial update
$$
    u_{\mathrm{trial}} = u_k - \alpha \delta_k,
$$
the step is accepted if the residual is reduced according to
$$
    \|F(u_{\mathrm{trial}})\|_2
    \leq
    \left(1 - \eta \alpha\right)\|F(u_k)\|_2,
$$
where $\eta$ is given by \inltt{AcceptReductionEta}. If the condition is not
satisfied, the scale is reduced by \inltt{BacktrackFactor}. The next nonlinear
iteration starts from the accepted scale, or from an enlarged scale if the first
trial was accepted.

To use this method, set
\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
    <I PROPERTY="NonlinearSolver" VALUE="NewtonBacktrack" />
</SOLVERINFO>
\end{lstlisting}

The available parameters and their default values are
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> NewtonScaleInit       = 1.0e-2 </P>
    <P> NewtonScaleMax        = 1.0e-1 </P>
    <P> NewtonScaleMin        = 1.0e-6 </P>
    <P> NewtonScaleGrowFactor = 2.0    </P>
    <P> BacktrackFactor       = 0.5    </P>
    <P> MaxBacktrackSteps     = 4      </P>
    <P> AcceptReductionEta    = 1.0e-4 </P>
</PARAMETERS>
\end{lstlisting}

In this variant, the Newton step is taken in the same direction as $\delta_k$, but the step length is adjusted to guarantee the decrease of the residuum.

\subsubsection{Line-search trust region}

The trust-region variant is similar to a backtracking variant in that it keeps the direction of the computed correction $\delta_k$ unchanged, only adjusting the step length.
Here, a trust radius $\Delta_k$ is used. If the Newton correction lies within the trust region, the step is taken, but if is too large, the applied correction is scaled to lie inside the current trust radius $\Delta_k$:
$$
    s_k =
    \begin{cases}
    \delta_k, & \|\delta_k\|_2 \leq \Delta_k, \\
    \displaystyle \frac{\Delta_k}{\|\delta_k\|_2}\delta_k,
    & \|\delta_k\|_2 > \Delta_k.
    \end{cases}
$$
The trial update is $u_{\mathrm{trial}} = u_k - s_k$. The step is accepted
using the ratio
$$
    \rho =
    \frac{\mathrm{ared}}{\mathrm{pred}},
    \qquad
    \mathrm{ared}
    =
    \|F(u_k)\|_2 - \|F(u_{\mathrm{trial}})\|_2.
$$
In this implementation, the predicted reduction is estimated from the applied
fraction of the Newton step. The trust radius is reduced when the model is poor
and enlarged when the accepted step lies on the trust-region boundary and gives
a good reduction.

To use this method, add
\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
    <I PROPERTY="NonlinearSolver" VALUE="NewtonTrustRegion" />
</SOLVERINFO>
\end{lstlisting}

The available parameters and default values are
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> TrustRadiusInit                         = 1.0e-2 </P>
    <P> TrustRadiusMin                          = 1.0e-8 </P>
    <P> TrustRadiusMax                          = 1.0e2  </P>
    <P> TrustRegionRhoAccept                    = 1.0e-1 </P>
    <P> TrustRegionRhoShrink                    = 2.5e-1 </P>
    <P> TrustRegionRhoGrow                      = 7.5e-1 </P>
    <P> TrustRegionShrinkFactor                 = 0.5    </P>
    <P> TrustRegionGrowFactor                   = 2.0    </P>
    <P> MaxTrustRegionSteps                     = 4      </P>
    <P> TrustRegionMaxFallbackResidualGrowth    = 10.0   </P>
</PARAMETERS>
\end{lstlisting}

\subsubsection{Hook step}

The hook-step method uses information generated by GMRES to solve a reduced
trust-region problem in the Krylov subspace. If GMRES constructs the Arnoldi
basis $V_m$ and the Hessenberg matrix $\bar{H}_m$, the step is written as
$$
    s_k = V_m y.
$$
The reduced hook-step problem is
$$
    \min_{\|y\|_2 \leq \Delta_k}
    \left\|
        \beta e_1 - \bar{H}_m y
    \right\|_2,
$$
where $\beta = \|F(u_k)\|_2$. If the unconstrained GMRES minimiser lies outside
the trust radius, the constrained step is obtained from
$$
    \left(\bar{H}_m^T\bar{H}_m + \mu I\right)y
    =
    \beta \bar{H}_m^T e_1,
    \qquad
    \|y\|_2 = \Delta_k,
$$
with a non-negative hook-step parameter $\mu$.

The predicted residual norm is computed from the reduced GMRES model,
$$
    \|r_{\mathrm{pred}}\|_2
    =
    \left\|
        \beta e_1 - \bar{H}_m y
    \right\|_2,
$$
and the acceptance ratio is
$$
    \rho =
    \frac{
        \|F(u_k)\|_2 - \|F(u_{\mathrm{trial}})\|_2
    }{
        \|F(u_k)\|_2 - \|r_{\mathrm{pred}}\|_2
    }.
$$
The hook step can therefore change both the length and direction of the Newton
correction inside the Krylov subspace.

This method requires GMRES:
\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
    <I PROPERTY="NonlinearSolver" VALUE="NewtonHookStep" />
    <I PROPERTY="LinSysIterSolver" VALUE="GMRES" />
</SOLVERINFO>
\end{lstlisting}

The available parameters and default values are
\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
    <P> TrustRadiusInit                         = 1.0e-2 </P>
    <P> TrustRadiusMin                          = 1.0e-8 </P>
    <P> TrustRadiusMax                          = 1.0e2  </P>
    <P> TrustRegionRhoAccept                    = 1.0e-1 </P>
    <P> TrustRegionRhoShrink                    = 2.5e-1 </P>
    <P> TrustRegionRhoGrow                      = 7.5e-1 </P>
    <P> TrustRegionShrinkFactor                 = 0.5    </P>
    <P> TrustRegionGrowFactor                   = 2.0    </P>
    <P> MaxTrustRegionSteps                     = 4      </P>
    <P> MaxTrustRegionGrowthSteps               = 3      </P>
    <P> TrustRegionMaxFallbackResidualGrowth    = 10.0   </P>
    <P> MeaningfulAredRel                       = 1.0e-3 </P>
    <P> MeaningfulAredAbs                       = 1.0e-12 </P>
</PARAMETERS>
\end{lstlisting}

The initial hook-step implementation requires GMRES data to be exported by the
linear solver and does not support left-preconditioned GMRES.

\subsection{Boundary Regions and Conditions}

Boundary conditions are defined by two XML elements. The first defines the
boundary regions in the domain in terms of composite entities from the
\inltt{GEOMETRY} section of the file. Each boundary region has a unique ID and
are defined as, 
\begin{lstlisting}[style=XMLStyle]
<BOUNDARYREGIONS>
    <B ID=[id]> [composite-list] </B>
    ...
</BOUNDARYREGIONS>
\end{lstlisting}
For example,
\begin{lstlisting}[style=XMLStyle]
<BOUNDARYREGIONS>
  <B ID="0"> C[2] </B>
  <B ID="1"> C[3] </B>
</BOUNDARYREGIONS>
\end{lstlisting}

The boundary regions can also optionally contain a name which is then used in the
multi-block VTK output to label the block descriptively rather than by ID, for
example
\begin{lstlisting}[style=XMLStyle]
<BOUNDARYREGIONS>
  <B ID="0" NAME="Wall"> C[2] </B>
  <B ID="1" NAME="Farfield"> C[3] </B>
</BOUNDARYREGIONS>
\end{lstlisting}

The second XML element defines, for each variable, the condition to impose on
each boundary region, and has the form,
\begin{lstlisting}[style=XMLStyle]
<BOUNDARYCONDITIONS>
    <REGION REF="[regionID]">
      <[type1] VAR="[variable1]" VALUE="[expression1]" />
      ...
      <[typeN] VAR="[variableN]" VALUE="[expressionN]" />
    </REGION>
    ...
</BOUNDARYCONDITIONS>
\end{lstlisting}
There should be precisely one \inltt{REGION} entry for each \inltt{B} entry
defined in the \inltt{BOUNDARYREGION} section above. For example, to impose a
Dirichlet condition on both variables for a domain with a single region, 
\begin{lstlisting}[style=XMLStyle] 
<BOUNDARYCONDITIONS>
  <REGION REF="0">
    <D VAR="u" VALUE="sin(PI*x)*cos(PI*y)" /> 
    <D VAR="v" VALUE="sin(PI*x)*cos(PI*y)" />
  </REGION>
</BOUNDARYCONDITIONS>
\end{lstlisting}
Boundary condition specifications may refer to any parameters defined in the
session file. The \inltt{REF} attribute corresponds to a defined boundary
region. The tag used for each variable specifies the type of boundary condition
to enforce.

\subsubsection{Dirichlet (essential) condition}
Dirichlet conditions are specified with the \inltt{D} tag.

\begin{tabular}{llll}
Projection & Homogeneous support & Time-dependent support & Dimensions \\
\toprule
CG & Yes & Yes & 1D, 2D and 3D \\
DG & Yes & Yes & 1D, 2D and 3D \\
HDG& Yes & Yes & 1D, 2D and 3D
\end{tabular}

Example:
\begin{lstlisting}[style=XMLStyle]
<!-- homogeneous condition -->
<D VAR="u" VALUE="0" />
<!-- inhomogeneous condition -->
<D VAR="u" VALUE="x^2+y^2+z^2" />
<!-- time-dependent condition -->
<D VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="x+t" />
\end{lstlisting}

\subsubsection{Neumann (natural) condition}
Neumann conditions are specified with the \inltt{N} tag.

\begin{tabular}{llll}
Projection & Homogeneous support & Time-dependent support & Dimensions \\
\toprule
CG & Yes & Yes & 1D, 2D and 3D \\
DG & No  & No  & 1D, 2D and 3D \\
HDG & ? & ? & ?
\end{tabular}

Example:
\begin{lstlisting}[style=XMLStyle]
<!-- homogeneous condition -->
<N VAR="u" VALUE="0" />
<!-- inhomogeneous condition -->
<N VAR="u" VALUE="x^2+y^2+z^2" />
<!-- time-dependent condition -->
<N VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="x+t" />
<!-- high-order pressure boundary condition (for IncNavierStokesSolver) -->
<N VAR="u" USERDEFINEDTYPE="H" VALUE="0" />
\end{lstlisting}

\subsubsection{Periodic condition}\label{sec:periodicBC}
Periodic conditions are specified with the \inltt{P} tag.

\begin{tabular}{lll}
Projection & Homogeneous support & Dimensions \\
\toprule
CG  & Yes & 1D, 2D and 3D \\
DG  & No  & 2D and 3D
\end{tabular}

Example:
\begin{lstlisting}[style=XMLStyle]
<BOUNDARYREGIONS>
  <B ID="0"> C[1] </B>
  <B ID="1"> C[2] </B>
</BOUNDARYREGIONS>

<BOUNDARYCONDITIONS>
  <REGION REF="0">
    <P VAR="u" VALUE="[1]" />
  </REGION>
  <REGION REF="1">
    <P VAR="u" VALUE="[0]" />
  </REGION>
</BOUNDARYCONDITIONS>
\end{lstlisting}

Periodic boundary conditions are specified in a significantly different form to
other conditions. The \inltt{VALUE} property is used to specify which
\inltt{BOUNDARYREGION} is periodic with the current region in square brackets.

Caveats:
\begin{itemize}
\item A periodic condition must be set for '''both''' boundary regions; simply
 specifying a condition for region 0 or 1 in the above example is not enough.
\item The order of the elements inside the composites defining periodic
boundaries is important. For example, if `C[0]` above is defined as edge IDs 
`{0,5,4,3}` and `C[1]` as `{7,12,2,1}` then edge 0 is periodic with edge 7, 5 
with 12, and so on.
\item For the above reason, the composites must also therefore be of the same
size.
\item In three dimensions, care must be taken to correctly align triangular
faces which are intended to be periodic. The top (degenerate) vertex should be 
aligned so that, if the faces were connected, it would lie at the same point on 
both triangles.

\item It is possible specify periodic boundaries that are related by a
  rotation about a cartesian axis. In three-dimensions it is necessary
  to specify the rotational arguments to allow the orientation of each
  periodic face to be determined. This is not required in
  two-dimensions. An example of how two periodic boundaries are
  related by a rotation about the x-axis of $PI/6$ is shown below. The
  last number specifies an optional tolerance to which the rotation is
  considered as equivalent (default value is $1e-8$).
  
  \begin{lstlisting}[style=XMLStyle]
<BOUNDARYREGIONS>
  <B ID="0"> C[1] </B>
  <B ID="1"> C[2] </B>
</BOUNDARYREGIONS>

<BOUNDARYCONDITIONS>
  <REGION REF="0">
    <P VAR="u" USERDEFINEDTYPE="Rotated:x:PI/6:1e-6"  VALUE="[1]" />
  </REGION>
  <REGION REF="1">
    <P VAR="u" USERDEFINEDTYPE="Rotated:x:-PI/6:1e-6"  VALUE="[0]" />
  </REGION>
</BOUNDARYCONDITIONS>
\end{lstlisting}


\end{itemize}

\subsubsection{Time-dependent boundary conditions}
Time-dependent boundary conditions may be specified through setting the
\inltt{USERDEFINEDTYPE} attribute and using the parameter \inltt{t} where the
current time is required. For example,
\begin{lstlisting}[style=XMLStyle]
<D VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="sin(PI*(x-t))" />
\end{lstlisting}

\subsubsection{Boundary conditions from file}
Boundary conditions can also be loaded from file. The following example is from
the Incompressible Navier-Stokes solver,
\begin{lstlisting}[style=XMLStyle]
<REGION REF="1">
  <D VAR="u" FILE="Test_ChanFlow2D_bcsfromfiles_u_1.bc" />
  <D VAR="v" VALUE="0" />
  <N VAR="p" USERDEFINEDTYPE="H" VALUE="0" />
</REGION>
\end{lstlisting}

Boundary conditions can also be loaded simultaneously from a file and from an 
expression (currently only implemented in 3D).
For example, in the scenario where a spatial boundary 
condition is read from a file, but needs to be modulated by a time-dependent 
expression:
\begin{lstlisting}[style=XMLStyle]
<REGION REF="1">
  <D VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="sin(PI*(x-t))"
             FILE="bcsfromfiles_u_1.bc" />
</REGION>
\end{lstlisting}

In the case where both \inltt{VALUE} and \inltt{FILE} are specified, the values
are multiplied together to give the final value for the boundary condition. 

\subsection{Functions}

Finally, multi-variable functions such as initial conditions and analytic
solutions may be specified for use in, or comparison with, simulations. These
may be specified using expressions (\inltt{<E>}) or imported from a file
(\inltt{<F>}) using the Nektar++ FLD file format

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="ExactSolution">
  <E VAR="u" VALUE="sin(PI*x-advx*t))*cos(PI*(y-advy*t))" />
</FUNCTION>
<FUNCTION NAME="InitialConditions">
  <F VAR="u" FILE="session.rst" />
</FUNCTION>
\end{lstlisting}

A restart file is a solution file (in other words an .fld renamed as .rst) where
the field data is specified. The expansion order used to generate the .rst file
must be the same as that for the simulation.
.pts files contain scattered point data which needs to be interpolated to the field.
For further information on the file format and the different interpolation schemes, see
section~\ref{s:utilities:fieldconvert:sub:interppointdatatofld}.
All filenames must be specified relative to the location of the .xml file.

With the additional argument \inltt{TIMEDEPENDENT="1"}, different files can be
loaded for each timestep. The filenames are defined using
\href{http://www.boost.org/doc/libs/1_56_0/libs/format/doc/format.html#syntax}{boost::format syntax}
where the step time is used as variable. For example, the function
\inltt{Baseflow} would load the files \inltt{U0V0\_1.00000000E-05.fld},
\inltt{U0V0\_2.00000000E-05.fld} and so on.

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="Baseflow">
       <F VAR="U0,V0" TIMEDEPENDENT="1" FILE="U0V0_%14.8E.fld"/>
</FUNCTION>
\end{lstlisting}

For .pts files, the time consuming computation of interpolation weights is only
performed for the first timestep. The weights are stored and reused in all subsequent steps, 
which is why all consecutive .pts files must use the same ordering, number and location of
data points.

Other examples of this input feature can be the insertion of a forcing term,

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="BodyForce">
  <E VAR="u" VALUE="0" />
  <E VAR="v" VALUE="0" />
</FUNCTION>
<FUNCTION NAME="Forcing">
  <E VAR="u" VALUE="-(Lambda + 2*PI*PI)*sin(PI*x)*sin(PI*y)" />
</FUNCTION>
\end{lstlisting}

or of a linear advection term

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="AdvectionVelocity">
  <E VAR="Vx" VALUE="1.0" />
  <E VAR="Vy" VALUE="1.0" />
  <E VAR="Vz" VALUE="1.0" />
</FUNCTION>
\end{lstlisting}

\subsubsection{Remapping variable names}

Note that it is sometimes the case that the variables being used in the solver
do not match those saved in the FLD file. For example, if one runs a
three-dimensional incompressible Navier-Stokes simulation, this produces an FLD
file with the variables \inltt{u}, \inltt{v}, \inltt{w} and \inltt{p}. If we
wanted to use this velocity field as input for an advection velocity, the
advection-diffusion-reaction solver expects the variables \inltt{Vx}, \inltt{Vy}
and \inltt{Vz}. We can manually specify this mapping by adding a colon to the
filename, indicating the variable names in the target file that align with the
desired function variable names. This gives a definition such as:

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="AdvectionVelocity">
  <F VAR="Vx,Vy,Vz" FILE="file.fld:u,v,w" />
</FUNCTION>
\end{lstlisting}

There are some caveats with this syntax:

\begin{itemize}
  \item The same number of fields must be defined for both the \inltt{VAR}
  attribute and in the comma-separated list after the colon. For example, the
  following is not valid:
  \begin{lstlisting}[style=XMLStyle,gobble=4]
    <FUNCTION NAME="AdvectionVelocity">
      <F VAR="Vx,Vy,Vz" FILE="file.fld:u" />
    </FUNCTION>\end{lstlisting}
  \item This syntax is not valid with the wildcard operator \inltt{*}, so one
  cannot write for example:
  \begin{lstlisting}[style=XMLStyle,gobble=4]
    <FUNCTION NAME="AdvectionVelocity">
      <F VAR="*" FILE="file.fld:u,v,w" />
    </FUNCTION>
  \end{lstlisting}
\end{itemize}

\subsubsection{Time-dependent file-based functions}

With the additional argument \inltt{TIMEDEPENDENT="1"}, different files can be
loaded for each timestep. The filenames are defined using
\href{http://www.boost.org/doc/libs/1_56_0/libs/format/doc/format.html#syntax}{boost::format
  syntax} where the step time is used as variable. For example, the function
\inltt{Baseflow} would load the files \inltt{U0V0\_1.00000000E-05.fld},
\inltt{U0V0\_2.00000000E-05.fld} and so on.

\begin{lstlisting}[style=XMLStyle]
<FUNCTION NAME="Baseflow">
  <F VAR="U0,V0" TIMEDEPENDENT="1" FILE="U0V0_%14.8R.fld" />
</FUNCTION>
\end{lstlisting}

Section~\ref{sec:xml:expressions} provides the list of acceptable
mathematical functions and other related technical details.

\subsection{Quasi-3D approach}

To generate a Quasi-3D appraoch with Nektar++ we only need to create a 2D or a
1D mesh, as reported above, and then specify the parameters to extend the
problem to a 3D case. For a 2D spectral/hp element problem, we have a 2D mesh
and along with the parameters we need to define the problem (i.e. equation type,
boundary conditions, etc.). The only thing we need to do, to extend it to a
Quasi-3D approach, is to specify some additional parameters which characterise
the harmonic expansion in the third direction. First we need to specify in the
solver information section that that the problem will be extended to have one
homogeneouns dimension; here an example

\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
  ...
  <I PROPERTY="HOMOGENEOUS"           VALUE="1D"                       />
</SOLVERINFO>
\end{lstlisting}

then we need to specify the parameters which define the 1D harmonic expanson
along the z-axis, namely the homogeneous length (LZ) and the number of modes in
the homogeneous direction (HomModesZ). \inltt{HomModesZ} corresponds also to the number
of quadrature points in the homogenous direction, hence on the number of 2D
planes discretized with a spectral/hp element method.

\begin{lstlisting}[style=XMLStyle]
<PARAMETERS>
  ...
  <P> HomModesZ     = 4       </P>
  <P> LZ            = 1.0     </P>
</PARAMETERS>
\end{lstlisting}

In case we want to create a Quasi-3D approach starting from a 1D spectral/hp
element mesh, the procedure is the same, but we need to specify the parameters
for two harmonic directions (in Y and Z direction). For Example,

\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
  ...
  <I PROPERTY="HOMOGENEOUS"           VALUE="2D"                         />
</SOLVERINFO>
<PARAMETERS>
  ...
  <P> HomModesY     = 10    </P>
  <P> LY            = 6.5   </P>
  <P> HomModesZ     = 6     </P>
  <P> LZ            = 2.0   </P>
</PARAMETERS>
\end{lstlisting}

By default the operations associated with the harmonic expansions are performed
with the Matrix-Vector-Multiplication (MVM) defined inside the code. The Fast
Fourier Transform (FFT) can be used to speed up the operations (if the FFTW
library has been compiled in ThirdParty, see the compilation instructions). To
use the FFT routines we need just to insert a flag in the solver information as
below:

\begin{lstlisting}[style=XMLStyle]
<SOLVERINFO>
  ...
  <I PROPERTY="HOMOGENEOUS"           VALUE="2D"                         />
  <I PROPERTY="USEFFT"                VALUE="FFTW"                       />
</SOLVERINFO>
\end{lstlisting}

The number of homogeneous modes has to be even. The Quasi-3D approach can be
created starting from a 2D mesh and adding one homogenous expansion or starting
form a 1D mesh and adding two homogeneous expansions. Not other options
available. In case of a 1D homogeneous extension, the homogeneous direction will
be the z-axis. In case of a 2D homogeneous extension, the homogeneous directions
will be the y-axis and the z-axis.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../user-guide"
%%% End:
