3.4 Filters

Filters are a method for calculating a variety of useful quantities from the field variables as the solution evolves in time, such as time-averaged fields and extracting the field variables at certain points inside the domain. Each filter is defined in a FILTER tag inside a FILTERS block which lies in the main NEKTAR tag. In this section we give an overview of the modules currently available and how to set up these filters in the session file.

Here is an example FILTER:

A filter has a name – in this case, FilterName – together with parameters which are set to user-defined values. Each filter expects different parameter inputs, although where functionality is similar, the same parameter names are shared between filter types for consistency. Numerical filter parameters may be expressions and so may include session parameters defined in the PARAMETERS section.

In the following we document the filters implemented. Note that some filters are solver-specific and will therefore only work for a given subset of the available solvers.

3.4.1 FieldConvert checkpoints

This filter applies a sequence of FieldConvert modules to the solution, writing an output file. An output is produced at the end of the simulation into session_fc.fld, or alternatively every M timesteps as defined by the user, into a sequence of files session_*_fc.fld, where * is replaced by a counter.

The following parameters are supported:

As an example, consider:

This will create a sequence of files named MyFile_*_fc.vtu containing isocontours. The result will be output every 100 time steps. Output directly to .vtu or .dat is currently only supported for isocontours. In other cases, the output should be a .fld file.

3.4.2 Time-averaged fields

This filter computes time-averaged fields for each variable defined in the session file. Time averages are computed by either taking a snapshot of the field every timestep, or alternatively at a user-defined number of timesteps N. An output is produced at the end of the simulation into session_avg.fld, or alternatively every M timesteps as defined by the user, into a sequence of files session_*_avg.fld, where * is replaced by a counter. This latter option can be useful to observe statistical convergence rates of the averaged variables.

This filter is derived from FieldConvert filter, and therefore support all parameters available in that case. The following additional parameter is supported:

As an example, consider:

This will create a file named MyAverageField.fld averaging the instantaneous fields every 10 time steps. The averaged field is however only output every 100 time steps.

3.4.3 Moving average of fields

This filter computes the exponential moving average (in time) of fields for each variable defined in the session file. The moving average is defined as:

with 0 < α < 1 and u₁ = u₁.

The same parameters of the time-average filter are supported, with the output file in the form session_*_movAvg.fld. In addition, either α or the time-constant τ must be defined. They are related by:

where t_s is the time interval between consecutive samples.

As an example, consider:

This will create a file named MyMovingAverage_movAvg.fld with a moving average sampled every 10 time steps. The averaged field is however only output every 100 time steps.

3.4.4 Reynolds stresses

This filter is an extended version of the time-average filter. It outputs not only the time-average of the fields, but also the Reynolds stresses. The same parameters supported in the time-average case can be used, for example:

By default, this filter uses a simple average. Optionally, an exponential moving average can be used, in which case the output contains the moving averages and the Reynolds stresses calculated based on them. For example:

3.4.5 Checkpoint fields

The checkpoint filter writes a checkpoint file, containing the instantaneous state of the solution fields at at given timestep. This can subsequently be used for restarting the simulation or examining time-dependent behaviour. This produces a sequence of files, by default named session_*.chk, where * is replaced by a counter. The initial condition is written to session_0.chk. Existing files are not overwritten, but renamed to e.g. session_0.bak0.chk. In case this file already exists, too, the chk-file is renamed to session_0.bak*.chk and so on.

The following parameters are supported:

For example, to output the fields every 100 timesteps we can specify:

3.4.6 History points

The history points filter can be used to evaluate the value of the fields in specific points of the domain as the solution evolves in time. By default this produces a file called session.his. For each timestep, and then each history point, a line is output containing the current solution time, followed by the value of each of the field variables. Commented lines are created at the top of the file containing the location of the history points and the order of the variables.

The following parameters are supported:

For example, to output the value of the solution fields at three points (1,0.5,0), (2,0.5,0) and (3,0.5,0) into a file TimeValues.his every 10 timesteps, we use the syntax:

3.4.7 ThresholdMax

The threshold value filter writes a field output containing a variable m, defined by the time at which the selected variable first exceeds a specified threshold value. The default name of the output file is the name of the session with the suffix _max.fld. Thresholding is applied based on the first variable listed in the session by default.

The following parameters are supported:

An example is given below:

which produces a field file threshold_max.fld.

3.4.8 ThresholdMin value

Performs the same function as the ThresholdMax filter but records the time at which the threshold variable drops below a prescribed value.

3.4.9 One-dimensional energy

This filter is designed to output the energy spectrum of one-dimensional elements. It transforms the solution field at each timestep into a orthogonal basis defined by the functions

where L_p is the p-th Legendre polynomial. This can be used to show the presence of, for example, oscillations in the underlying field due to numerical instability. The resulting output is written into a file called session.eny by default. The following parameters are supported:

An example syntax is given below:

3.4.10 Modal energy

This filter calculates the time-evolution of the kinetic energy. In the case of a two- or three-dimensional simulation this is defined as

However if the simulation is written as a one-dimensional homogeneous expansion so that

then we instead calculate the energy spectrum

Note that in this case, each component of û_k is a complex number and therefore N = HomModesZ∕2 lines are output for each timestep. This is a particularly useful tool in examining turbulent and transitional flows which use the homogeneous extension. In either case, the resulting output is written into a file called session.mdl by default.

The following parameters are supported:

An example syntax is given below:

3.4.11 Aerodynamic forces

This filter evaluates the aerodynamic forces along a specific surface. The forces are projected along the Cartesian axes and the pressure and viscous contributions are computed in each direction.

The following parameters are supported:

An example is given below:

During the execution a file named DragLift.frc will be created and the value of the aerodynamic forces on boundaries 1 and 2, defined in the GEOMETRY section, will be output every 10 time steps.

3.4.12 Kinetic energy and enstrophy

The purpose of this filter is to calculate the kinetic energy and enstrophy

where μ(Ω) is the volume of the domain Ω. This produces a file containing the time-evolution of the kinetic energy and enstrophy fields. By default this file is called session.eny where session is the session name.

The following parameters are supported:

To enable the filter, add the following to the FILTERS tag: