3.3 Conditions

The final section of the file defines parameters and boundary conditions which define the nature of the problem to be solved. These are enclosed in the CONDITIONS tag.

3.3.1 Parameters

Parameters may be required by a particular solver (for instance time-integration parameters or solver-specific parameters), or arbitrary and only used within the context of the session file (e.g. parameters in the definition of an initial condition). All parameters are enclosed in the PARAMETERS XML element.

2    ... 

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


For example,

1<P> NumSteps = 1000              </P> 
2<P> TimeStep = 0.01              </P> 
3<P> FinTime  = NumSteps*TimeStep </P>

3.3.2 Solver Information

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

2  <I PROPERTY="EQTYPE"                VALUE="UnsteadyAdvection"    /> 
3  <I PROPERTY="Projection"            VALUE="Continuous"           /> 
4  <I PROPERTY="TimeIntegrationMethod" VALUE="ClassicalRungeKutta4" /> 

The list of available solvers in Nektar++ can be found in Part II. Drivers

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

The default driver is called Standard and executes the following steps:

  1. Prints out on screen a summary of all the conditions defined in the input file.
  2. Sets up the initial and boundary conditions.
  3. Calls the solver defined by SolverType in the SOLVERINFO XML element.
  4. Writes the results in the output (.fld) file.

In the following example, the driver Standard is used to manage the execution of the incompressible Navier-Stokes equations:

2    <I PROPERTY="EQTYPE" VALUE="UnsteadyNavierStokes" /> 
3    <I PROPERTY="SolverType" VALUE="VelocityCorrectionScheme" /> 
4    <I PROPERTY="Projection" VALUE="Galerkin" /> 
5    <I PROPERTY="TimeIntegrationMethod" VALUE="IMEXOrder2" /> 
6    <I PROPERTY="Driver" VALUE="Standard" /> 

If no driver is specified in the session file, the driver Standard is called by default. Other drivers can be used and are typically focused on specific applications. As described in Sec. 8.3.1 and 8.4.1, the other possibilities are:

3.3.3 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

2  <V ID="0"> u </V> 
3  <V ID="1"> v </V> 

3.3.4 Global System Solution Information

This section allows you to specify the global system solution parameters which is particularly useful when using an iterative solver. An example of this section is as follows:

2  <V VAR="u,v,w"> 
3    <I PROPERTY="GlobalSysSoln"             VALUE="IterativeStaticCond" /> 
4    <I PROPERTY="Preconditioner"            VALUE="LowEnergyBlock"/> 
5    <I PROPERTY="IterativeSolverTolerance"  VALUE="1e-8"/> 
6  </V> 
7  <V VAR="p"> 
8    <I PROPERTY="GlobalSysSoln"             VALUE="IterativeStaticCond" /> 
9    <I PROPERTY="Preconditioner"     VALUE="FullLinearSpaceWithLowEnergyBlock"/> 
10    <I PROPERTY="IterativeSolverTolerance"  VALUE="1e-6"/> 
11  </V> 

The above section specifies that the global solution system for the variables "u,v,w" should use the iIerativeStaticCond approach with the LowEnergyBlock preconditioned and an iterative tolerance of 1e-6. Where as the variable "p" which also is solved with the IterativeStaticCond approach should use the FullLinearSpaceWithLowEnergyBlock and an iterative tolerance of 1e-8.

Other parameters which can be specified include SuccessiveRHS.

The parameters in this section override those specified in the Parameters section.

3.3.5 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 GEOMETRY section of the file. Each boundary region has a unique ID and are defined as,

2    <B ID=[id]> [composite-list] </B> 
3    ... 

For example,

2  <B ID="0"> C[2] </B> 
3  <B ID="1"> C[3] </B> 

The second XML element defines, for each variable, the condition to impose on each boundary region, and has the form,

2    <REGION REF="[regionID]"> 
3      <[type1] VAR="[variable1]" VALUE="[expression1]" /> 
4      ... 
5      <[typeN] VAR="[variableN]" VALUE="[expressionN]" /> 
6    </REGION> 
7    ... 

There should be precisely one REGION entry for each B entry defined in the BOUNDARYREGION section above. For example, to impose a Dirichlet condition on both variables for a domain with a single region,

2  <REGION REF="0"> 
3    <D VAR="u" VALUE="sin(PI*x)*cos(PI*y)" /> 
4    <D VAR="v" VALUE="sin(PI*x)*cos(PI*y)" /> 
5  </REGION> 

Boundary condition specifications may refer to any parameters defined in the session file. The REF attribute corresponds to a defined boundary region. The tag used for each variable specifies the type of boundary condition to enforce. Dirichlet (essential) condition

Dirichlet conditions are specified with the D tag.

Projection Homogeneous support Time-dependent support Dimensions
CG Yes Yes 1D, 2D and 3D
DG Yes Yes 1D, 2D and 3D
HDG Yes Yes 1D, 2D and 3D


1<!-- homogeneous condition --> 
2<D VAR="u" VALUE="0" /> 
3<!-- inhomogeneous condition --> 
4<D VAR="u" VALUE="x^2+y^2+z^2" /> 
5<!-- time-dependent condition --> 
6<D VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="x+t" /> Neumann (natural) condition

Neumann conditions are specified with the N tag.

Projection Homogeneous support Time-dependent support Dimensions
CG Yes Yes 1D, 2D and 3D
DG No No 1D, 2D and 3D
HDG ? ? ?


1<!-- homogeneous condition --> 
2<N VAR="u" VALUE="0" /> 
3<!-- inhomogeneous condition --> 
4<N VAR="u" VALUE="x^2+y^2+z^2" /> 
5<!-- time-dependent condition --> 
6<N VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="x+t" /> 
7<!-- high-order pressure boundary condition (for IncNavierStokesSolver) --> 
8<N VAR="u" USERDEFINEDTYPE="H" VALUE="0" /> Periodic condition

Periodic conditions are specified with the P tag.

Projection Homogeneous support Dimensions
CG Yes 1D, 2D and 3D
DG No 2D and 3D


2  <B ID="0"> C[1] </B> 
3  <B ID="1"> C[2] </B> 
7  <REGION REF="0"> 
8    <P VAR="u" VALUE="[1]" /> 
9  </REGION> 
10  <REGION REF="1"> 
11    <P VAR="u" VALUE="[0]" /> 
12  </REGION> 

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

Caveats: Time-dependent boundary conditions

Time-dependent boundary conditions may be specified through setting the USERDEFINEDTYPE attribute and using the parameter t where the current time is required. For example,

1<D VAR="u" USERDEFINEDTYPE="TimeDependent" VALUE="sin(PI*(x-t))" /> Boundary conditions from file

Boundary conditions can also be loaded from file. The following example is from the Incompressible Navier-Stokes solver,

1<REGION REF="1"> 
2  <D VAR="u" FILE="Test_ChanFlow2D_bcsfromfiles_u_1.bc" /> 
3  <D VAR="v" VALUE="0" /> 

3.3.6 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 (<E>) or imported from a file (<F>) using the Nektar++ FLD file format

1<FUNCTION NAME="ExactSolution"> 
2  <E VAR="u" VALUE="sin(PI*x-advx*t))*cos(PI*(y-advy*t))" /> 
4<FUNCTION NAME="InitialConditions"> 
5  <F VAR="u" FILE="session.rst" /> 

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 13.3.9. All filenames must be specified relative to the location of the .xml file.

With the additional argument TIMEDEPENDENT="1", different files can be loaded for each timestep. The filenames are defined using boost::format syntax where the step time is used as variable. For example, the function Baseflow would load the files U0V0_1.00000000E-05.fld, U0V0_2.00000000E-05.fld and so on.

1<FUNCTION NAME="Baseflow"> 
2       <F VAR="U0,V0" TIMEDEPENDENT="1"FILE="U0V0_%14.8E.fld"/> 

For .pts files, the time consuming computation of interpolation weights in 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,

1<FUNCTION NAME="BodyForce"> 
2  <E VAR="u" VALUE="0" /> 
3  <E VAR="v" VALUE="0" /> 
5<FUNCTION NAME="Forcing"> 
6  <E VAR="u" VALUE="-(Lambda + 2*PI*PI)*sin(PI*x)*sin(PI*y)" /> 

or of a linear advection term

1<FUNCTION NAME="AdvectionVelocity"> 
2  <E VAR="Vx" VALUE="1.0" /> 
3  <E VAR="Vy" VALUE="1.0" /> 
4  <E VAR="Vz" VALUE="1.0" /> 
5</FUNCTION> 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 u, v, w and p. If we wanted to use this velocity field as input for an advection velocity, the advection-diffusion-reaction solver expects the variables Vx, Vy and Vz.

We can manually specify this mapping by adding a colon to the

1<FUNCTION NAME="AdvectionVelocity"> 
2  <F VAR="Vx,Vy,Vz" FILE="file.fld:u,v,w" /> 

There are some caveats with this syntax: Time-dependent file-based functions

With the additional argument TIMEDEPENDENT="1", different files can be loaded for each timestep. The filenames are defined using boost::format syntax where the step time is used as variable. For example, the function Baseflow would load the files U0V0_1.00000000E-05.fld, U0V0_2.00000000E-05.fld and so on.

1<FUNCTION NAME="Baseflow"> 
2  <F VAR="U0,V0" TIMEDEPENDENT="1" FILE="U0V0_%14.8R.fld" /> 

Section 3.6 provides the list of acceptable mathematical functions and other related technical details.

3.3.7 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

2  <I PROPERTY="SolverType"            VALUE="VelocityCorrectionScheme"/> 
3  <I PROPERTY="EQTYPE"                VALUE="UnsteadyNavierStokes"/> 
4  <I PROPERTY="AdvectionForm"         VALUE="Convective"/> 
5  <I PROPERTY="Projection"            VALUE="Galerkin"/> 
6  <I PROPERTY="TimeIntegrationMethod" VALUE="IMEXOrder2"/> 
7  <I PROPERTY="HOMOGENEOUS"           VALUE="1D"/> 

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). HomModesZ corresponds also to the number of quadrature points in the homogenous direction, hence on the number of 2D planes discretized with a specral/hp element method.

2  <P> TimeStep      = 0.001   </P> 
3  <P> NumSteps      = 1000    </P> 
4  <P> IO_CheckSteps = 100     </P> 
5  <P> IO_InfoSteps  = 10      </P> 
6  <P> Kinvis        = 0.025   </P> 
7  <P> HomModesZ     = 4       </P> 
8  <P> LZ            = 1.0     </P> 

In case we want to create a Quasi-3D approach starting form 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,

2  <I PROPERTY="EQTYPE"                VALUE="UnsteadyAdvectionDiffusion" /> 
3  <I PROPERTY="Projection"            VALUE="Continuous"/> 
4  <I PROPERTY="HOMOGENEOUS"           VALUE="2D"/> 
5  <I PROPERTY="DiffusionAdvancement"  VALUE="Implicit"/> 
6  <I PROPERTY="AdvectionAdvancement"  VALUE="Explicit"/> 
7  <I PROPERTY="TimeIntegrationMethod" VALUE="IMEXOrder2"/> 
10  <P> TimeStep      = 0.001 </P> 
11  <P> NumSteps      = 200   </P> 
12  <P> IO_CheckSteps = 200   </P> 
13  <P> IO_InfoSteps  = 10    </P> 
14  <P> wavefreq      = PI    </P> 
15  <P> epsilon       = 1.0   </P> 
16  <P> Lambda        = 1.0   </P> 
17  <P> HomModesY     = 10    </P> 
18  <P> LY            = 6.5   </P> 
19  <P> HomModesZ     = 6     </P> 
20  <P> LZ            = 2.0   </P> 

By default the opeartions associated with the harmonic expansions are performed with the Matix-Vector-Multiplication (MVM) defined inside the code. The Fast Fourier Transofrm (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:

2  <I PROPERTY="EQTYPE"                VALUE="UnsteadyAdvectionDiffusion" /> 
3  <I PROPERTY="Projection"            VALUE="Continuous"/> 
4  <I PROPERTY="HOMOGENEOUS"           VALUE="2D"/> 
5  <I PROPERTY="DiffusionAdvancement"  VALUE="Implicit"/> 
6  <I PROPERTY="AdvectionAdvancement"  VALUE="Explicit"/> 
7  <I PROPERTY="TimeIntegrationMethod" VALUE="IMEXOrder2"/> 
8  <I PROPERTY="USEFFT"                VALUE="FFTW"/> 

The number of homogenenous modes has to be even. The Quasi-3D apporach 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.