25. Plugins for initial and boundary conditions

This chapter describes several methods for imposing special solutions at the startup of the simulation and/or at the boundaries of the domain. One could think of irregular waves, solutions taken from another ComFLOW simulation or even results obtained with a different simulation package.

ComFLOW is capable of importing external data by means of shared-library plug-ins. The can include external data of any sort, for example stored on disk, but also obtained real-time from a different model or software package by means of a custom plug-in. Data can be loaded by ComFLOW directly without the need of additional preprocessing tools. If information is needed during the simulation, ComFLOW calls functions in the shared library in order to obtain the local flow solution. Depending on the simulation settings this can happen during initialization of the solution or at the inflow boundaries of the domain.

The shared library satisfies a very simple interface making it relatively straightforward to implementation your own special solution. This is explained in more detail in 25.3.

25.1. Getting started

Importing external data in ComFLOW requires the following three steps:

  1. Select the desired plug-in (shared library) to use.

    The shared library that provides the external data can be selected by means of the sub-key /comflow/coupling/external_solution/ in the XML input file, for example:

    The attribute @specialbc_dllfile specifies the filename or full path of the shared library that defines the ComFLOW plug-in. For cross-platform compatibility of the ComFLOW input file it is recommended to omit the file extension of the shared library (.so or .dll). Similarly it is possible to omit the prefix lib when running ComFLOW on Linux.

    If only a filename is provided, ComFLOW searches for the shared library at the following locations:

    • LD_LIBRARY_PATH,
    • the sub-directories bin/linux/plugins and lib/linux of the ComFLOW distribution.

    On Windows operating systems the shared library (DLL) has to be placed next to the ComFLOW executables or the full path to the library has to be specified.

    The attribute @specialbc_initialize indicates if the external solution is used to initialize the flow field and the attribute @specialbc_ramp indicates if ramping is applied for smooth startup of the simulation.

  2. Specify the initial and boundary conditions that are based on the special solution.

    In order to switch on or off flow initialization with the special solution set the parameter initialize of the key /comflow/external_solution/ to either 1 or 0. If flow initialization is switched on, the velocity field, pressure and surface elevation are taken equal to the special solution at startup of the simulation.

    At the boundaries of the domain the special solution can be imposed using two types of boundary conditions:

    • velocity boundary condition (type 52):

      At these boundaries the velocities and surface elevation are taken equal to the special solution. This is typically the best boundary condition to use at the inflow boundary. Most practical applications do not need this boundary condition. It is recommended to use an outflow condition such as the ABC instead. Example:

      <boundaries>
  <boundary io="52">
        0.0   0.0  -10.0 10.0  -20.0 5.0
  </boundary>
  <boundary io="11">
      100.0 100.0  -10.0 10.0  -20.0 5.0
  </boundary>
</boundaries>

    • pressure boundary condition (type 53)

      At these boundaries the pressure is taken equal to the special solution. The rest of the flow properties are extrapolated from the interior. Example:

      <boundaries>
  <boundary io="53">
      100.0 100.0  -10.0 10.0  -20.0 5.0
  </boundary>
</boundaries>

  3. Provide settings for the selected special solution.

    This last step depends on the selected special solution.

25.2. Prebuilt plug-ins

25.2.1. Linear wave superposition

The library linearwavesuperposition allows you to define a solution based on the superposition of one or more linear waves. Settings have to be provided in an additional INI input file ${INPUT}/linearwavesuperposition.ini.

Example:

;; parameters for superposition of linear waves
om_cutoff = 2.0
wd = 27.0
componentsfile = ${INPUT}/components.in

The parameters in this file are explained as follows:

  • wd This mandatory parameter specifies the water depth expressed in meters, its value must be positive.

  • om_cutoff This mandatory parameter gives a cut-off threshold expressed in radians per second for high frequency components.

  • componentsfile: This optional parameter gives the location of the file specifying the wave components (see directly below). By default this parameter has value ${INPUT}/components.in. The parameter can be either an absolute path or a relative path with respect to the root simulation directory. The file divider has to be file system compliant.

    The first line of the file specifies the number of wave components, say n, followed by n lines, each containing three space-separated values for the amplitude, frequency, and phase respectively, e.g.

    2                                    <-- n
0.09784    0.04188   -2.41249        <-- amp(1) omeg(1) phas(1)
0.08932    0.06282    0.89072        <-- amp(2) omeg(2) phas(2)

25.2.2. HDF5 reader

Using the hdf5reader plug-in it is possible to set initial conditions and boundary conditions by importing field data from an HDF5 file. Possible applications include coupling to other ComFLOW simulations or data obtained from experiments or other flow models.

The settings for this plug-in can be specified in the INI file ${INPUT}/hdf5reader.ini. For example:

;; root directory of the simulation to take the solution from
hdf5file = ${OUTPUT}/../2d_simulation/specialbox.h5

;; time shift (the data is read from location t[comflow] + time_shift)
time_shift = 150.0

The parameters in this file are explained as follows:

  • hdf5file: This mandatory parameter specifies the location of the HDF5 file that provides the data for the initial and boundary conditions. It is possible to use relative paths, however the file separator must be system compliant and on Linux the path is case sensitive.
  • time_shift: This optional parameter can be used to time-shift the special box output of the coupled simulation. For example, if the data in the HDF5 file starts at t=20.0 [s], then specify a value of time_shift = 20.0 to shift the output to the starting time of the coupled simulation (t=0.0).

Where possible linear interpolation is used to project the external data on the computational grid of ComFLOW. If the requested points fall outside the range of the HDF5 file, constant extrapolation is applied (for example when coupling a 3D simulation to an HDF5 file with 2D data).

25.2.3. Python parser

The Python plug-in pythonparser allows to specify initial and boundary conditions using a Python-3 script. The Python script defines functions in a similar fashion as Fortran or C(++) plug-ins.

For illustration purposes consider the following example that defines a basic Couette-Poiseuille flow. The setup of the Python parser have to be provided in the INI file ${INPUT}/pythonparser.ini:

;; parameters for the Python parser plug-in
pythonfile = ${INPUT}/poiseuille.py

The actual plug-in is then defined in the Python script ${INPUT}/poiseuille.py:

########################################################################
# Example: uniform + Couette + Poiseuille flow
########################################################################

from math import acos, asin, cos, sin

#
# Solution properties:
#
phi    = 45.
theta  = 45.
plane  = 1
p0     = 0.
x0     = [0., 0., 0.]

radius = 0.5
vel0   = 0.0      # uniform velocity component
vel1   = 0.5      # linear velocity component (Couette)
vel2   = 0.5      # quadratic velocity component (Poiseuille)
mu     = 1e-2
rho    = 1.
nu     = mu/rho

pi     = acos(-1.)
phi    = phi*pi/180.
theta  = theta*pi/180.




########################################################################
# ComFLOW interface
########################################################################

def VelocityX(i,j,k,xpt,ypt,zpt,t):
    d = [ xpt-x0[0], ypt-x0[1], zpt-x0[2] ]
    r = (d[0]*e2[0]+d[1]*e2[1]+d[2]*e2[2])/radius
    u = e1[0] * ( vel2 * ( 1.0 - r*r ) + vel1 * ( .5 + r ) + vel0 )
    return u

def VelocityY(i,j,k,xpt,ypt,zpt,t):
    d = [ xpt-x0[0], ypt-x0[1], zpt-x0[2] ]
    r = (d[0]*e2[0]+d[1]*e2[1]+d[2]*e2[2])/radius
    v = e1[1] * ( vel2 * ( 1.0 - r*r ) + vel1 * ( .5 + r ) + vel0 )
    return v

def VelocityZ(i,j,k,xpt,ypt,zpt,t):
    d = [ xpt-x0[0], ypt-x0[1], zpt-x0[2] ]
    r = (d[0]*e2[0]+d[1]*e2[1]+d[2]*e2[2])/radius
    w = e1[2] * ( vel2 * ( 1.0 - r*r ) + vel1 * ( .5 + r ) + vel0 )
    return w

def DynamicPressure(i,j,k,xpt,ypt,zpt,t):
    d = [ xpt-x0[0], ypt-x0[1], zpt-x0[2] ]
    r = (d[0]*e1[0]+d[1]*e1[1]+d[2]*e1[2])/radius
    q = p0 + r * dpds
    return q

def SurfaceElevation(i,j,x,y,t):
    return 0.

def Init():
    global e1, e2, e3, dpds

    e1 = [ cos(theta)*cos(phi), cos(theta)*sin(phi), -sin(theta) ]
    plane = 1
    if plane==1:
      # profile angle 1 (ref. = Y-axis)
      e2 = [ -sin(phi), cos(phi), 0.0 ]
      # tertiary direction (ref. = Z-axis, not used)
      e3 = [ sin(theta)*cos(phi), sin(theta)*sin(phi), cos(theta) ]
    elif plane==2:
      # profile angle 1 (ref. = Z-axis)
      e2 = [ sin(theta)*cos(phi), sin(theta)*sin(phi), cos(theta) ]
      # tertiary direction (ref. = Y-axis, not used)
      e3 = [ -sin(phi), cos(phi), 0.0 ]
    else:
      e2 = e1
      e3 = e1

    if plane==0:
      dpds = - 4.0*nu*vel2/(radius**2)
    else:
      dpds = - 2.0*nu*vel2/(radius**2)

    return 0.

def Prepare(t,mode):
    return 0.

def Cleanup():
    return 0.

25.3. Creating a custom plug-in

Plug-ins are implemented by means of shared libraries that define a set of functions according to a specific interface. The coupling to the shared library is based on the FORTRAN ISO_C_BINDING standard which means that the shared library can be written either in Fortran (using the same ISO_C_BINDING standard) or in C(++).

Details of the interface can be found in the Fortran and C(++) files located in the sub-directory src_public/plugins/interface of the ComFLOW distribution. A ComFLOW plug-in defines the following functions:

  • VelocityX
  • VelocityY
  • VelocityZ
  • DynamicPressure
  • SurfaceElevation
  • Init
  • Prepare
  • Cleanup