19. Simulation output

In this chapter the post-processing capabilities of ComFLOW are described in more detail. Technical information concerning the various file formats are described in Chapter 28.

All post-processing settings that are described in this chapter have to be specified inside the key /comflow/output/ of the XML input file ${INPUT}/comflow.cfi. For a detailed documentation of individual keys and attributes please consult Chapter 26.

All output objects have in common that a time interval can be specified with one or more of the attributes @dt (the output time interval), @nr (total number of requested output instances), @tmin (starting time for output), @tmax (end time for output). These attributes can be specified per output category (e.g. fill boxes) or per individual output object (a specific fill box). Rules for setting the output interval can be found in Section 26.2.

Most of the output objects can be set to follow a moving body in the course of the simulation. This can be realized by setting the attribute @moving to "true" in the corresponding XML sub-key (more details follow below).

19.2. Snapshot file series

The ComFLOW program allows you to specify one or more sets of snapshot file series. For each of these file series separate time intervals, starting times and ending times can be specified. Furthermore it is possible to select one or more regions (slices or boxes) of the flow domain that need to be included in the output.

19.2.1. VTK snapshots

ComFLOW can write snapshots in the XML-based VTK format (using appended binary data). The time interval can be controlled with the attributes @dt, @tmin and @tmax as explained in Section 26.2. The snapshots are stored in the directory `${OUTPUT}/vtk with names cmf3d####.vtu and cmf3d####_info.vtu. The former file series contains the actual simulation results. The latter contains additional information about the computational grid (e.g. the block layout of the adaptive grid).

19.2.2. MATLAB snapshot files

Snapshot file series can be added to ComFLOW by inserting one or more keys output/snapshots/snapshot[*]. For each snapshot file series the following options can be specified:

  • @name: Name of the file series. The generated snapshots will have file names $NAME####.dat, where $NAME is replaced by the name of the file series and #### by the index of the output file. NB: The MATLAB post-processor of ComFLOW currently only allows to view files series with the names cmf2d, cmf3d, cmfbox.
  • @tmin, @tmax, @dt, @nr: An output interval as explained in Section 26.2.
  • @directory [Default: data]: Output directory for this file series . The output directory is automatically created by ComFLOW.
  • @extension [Default: .dat]: By means of this attribute it is possible to change the file extension of the snapshot files.

Inside snapshot[*]/, boxes can be specified in order to include regions of the flow domain in the snapshot. The entire flow domain can be included as follows:

<snapshots>
    <snapshot>
        <box everywhere="true"/>
    </snapshot>
</snapshots>

Slices can be included as follows:

<snapshots>
    <snapshot>
        <box x="2.0"/>  <!-- slice at X=2.0 -->
        <box y="3.0"/>  <!-- slice at Y=3.0 -->
        <box z="4.0"/>  <!-- slice at Z=4.0 -->
    </snapshot>
</snapshots>

In order to include an arbitrary region use the following form:

<snapshots>
    <snapshot>
        <!-- box covering the region
             (0.0<x<1.0, -0.5<y<0.5, -10.0<z<2.0) -->
        <box> 0.0 1.0 -0.5 0.5 -10.0 2.0  </box>
    </snapshot>
</snapshots>

Warning

The in-house ComFLOW snapshot format has become obsoleted. As of version 4.1 the MATLAB post-processor also supports VTK snapshot files. The VTK data format provides compatibility with other visualization programs (e.g. Visit, Tecplot) and is therefore recommended.

Warning

By default snapshot series do not contain any boxes hence not specifying any boxes results in empty (!) output files. The only exception to this rule is the predefined snapshot file series cmf3d which already includes one box covering the entire domain.

At startup of the simulation an overview is given of the file series, the selected box regions and the expected number of output files. This summary can also be found in the output file comflow.out.

19.2.2.1. Extra variables

By default snapshot include the velocity field (u, v, w), the pressure field (p), information about the geometry (fb) and the liquid distribution (fs). For two-phase simulations also the gas density and pressure are included (rhog, pgas).

Extra grid variables can be included by inserting keys output/variable[*]/. For example, the following XML statements can be used to include the cell-face apertures in the snapshot files:

<variable name="ax" longname="ApertureX"/>
<variable name="ay" longname="ApertureY"/>
<variable name="az" longname="ApertureZ"/>

The attribute @name specifies the (internal) name of the requested grid variable. By means of the attribute @longname the variable can be renamed in the snapshot file. The requested variables are included in all snapshot file series.

19.2.2.2. Example

The following example illustrates how to setup a snapshot series with customized output regions, storage locations and time intervals. The snapshot files will also contain the apertures ax, ay and az. Note that, for illustration purposes, the example also contains an empty snapshot series.

<comflow>
   <output>

      <snapshots>
          <snapshot name="3dextra" directory="data3d/" dt="0.05"
                    tmin="20." tmax="21.">
             <box everywhere="1"/>
          </snapshot>

          <snapshot name="2dextra" directory="data2d/" dt="0.02"
                    tmin="10." tmax="20.">
             <box x="0.5"/>
             <box y="-0.25"/>
             <box z="0.1"/>
             <box> 0.5 1.0 -0.5 0.0 0.0 1.0 </box>
          </snapshot>

          <snapshot name="cmf2d" directory="data/" dt="0.05">
             <box> 0.5 1.0 -0.5 0.0 0.0 1.0 </box>
          </snapshot>

          <snapshot name="empty" directory="data/">
          </snapshot>
      </snapshots>

      <variable name="ax" longname="ApertureX"/>
      <variable name="ay" longname="ApertureY"/>
      <variable name="az" longname="ApertureZ"/>

   </output>
</comflow>

During the start of GEODEF and ComFLOW an overview is presented of the snapshot file series, the selected output regions and the expected number of output files during the course of the simulation. It is recommended to check this overview, which is also written to comflow.out, to see if everything has been set up correctly.

19.3. Monitoring output

ComFLOW provides several output methods for high-frequency monitoring of the simulation results. Output can be generated at individual points in the domain (see Section 19.3.1) as well as along curves or surfaces (see Section 19.3.2).

19.3.1. Points

A monitor point can be defined by inserting a sub-key ``/comflow/output/monitoring/point/}. The usual time and motion attributes can be set.

  • @name: Name of the monitor point.
  • @tmin, @tmax, @dt, @nr: An output interval as explained in Section 26.2.
  • @moving [Default: "false"]: If this option is set to "true", the position of the monitoring object follows the moving object. By default the monitor point remains at a fixed position.

The monitor point is defined by its (initial) coordinates which have to be specified in the body of the XML key. The following example defines a moving monitor point having initial location (1,2,3) and an output interval of 0.1 [s] between time instances 0 [s] and 100 [s].

<output>
    <monitoring>
        <point tmin="0." tmax="100." dt=".1" moving="true">
                1.0  2.0  3.0
        </point>
    </monitoring>
</output>

19.3.2. Curves and surfaces

To allow for monitoring output on complex subsections of the computational domain, ComFLOW provides the option of using monitor curves or surfaces. Monitoring curves and surfaces can be used for the following purposes:

  • detailed plots on non-grid-aligned surfaces or curves,
  • force calculations on non-grid-aligned curves (2-D) or surfaces (3-D), e.g. (a section of) the hull of a vessel.

Monitor surfaces can be created by inserting one or more keys /comflow/output/monitoring/surface[*]/. The shape and initial position of the surface or curve has to be defined in an additional input file which will be illustrated by the following two examples.

19.3.2.1. A 2-D example

The following example file wedge.in defines a 2-D curve around a wedge:

2                               # 2-D/3-D coordinates
X Z Y                           # permutation of coordinates
2                               # curve (2) or surface (3)
3                               # number of vertices (N)
 0.0   0.05                     # vertex 1
 0.8   0.51188                  # ...
-0.8   0.51188                  # vertex N
3                               # number of line pieces (M)
1 2                             # line piece 1
2 3                             # ...
3 1                             # line piece M

On the first line the number of coordinates has to be specified. The specified coordinates can be permuted to map the surface on a possibly different coordinate system in the ComFLOW simulation. In this example the 2-D curve is defined in the XZ-plane, the Y coordinate is automatically set by ComFLOW to the center of the domain. On line 4 the number of vertices N is given followed by N lines of coordinate pairs. Then the number of line pieces M is given followed by M lines of vertex index pairs.

19.3.2.2. A 3-D example

The following example file box.in defines a surface around a simple box.

On the first line again the number of coordinates has to be specified. The specified coordinates can be permuted to map the surface on a possibly different coordinate system in the ComFLOW simulation. In this example the original coordinate system is used. On line 4 the number of vertices N is given followed by N lines of coordinate triplets. Then the number of faces M is given followed by M lines of vertex index triplets.

Elements are automatically split until a certain threshold relative to the grid spacing is reached. The maximum number of splitting levels can be specified with attribute @maxsplit (Default: 6) and the threshold relative to the grid spacing can be set with the attribute @threshold (Default: 1). The location of the additional input file has to be specified in the attribute @filename.

Monitoring surfaces can generate two types of output (also concurrently):

  • Detailed binary output of the pressure distribution along the surface (or curve). The output is written to a binary file surface####.dat (or curve####.dat). The contents of this file can be visualized using the MATLAB post-processor application. A MATLAB script is included in the ComFLOW distribution to illustrate the binary file format.
  • Total force across the surface. ComFLOW can calculate the total force across the surface (or curve) and write this to an ASCII file surface####.frc (or curve####.frc). The forces are calculated in the coordinate system as specified in the input file for the monitoring surface, irregardless of the actual position and rotation in the ComFLOW simulation. NB: Note that force calculations are only possible on curves in 2-D simulations. Furthermore, ComFLOW assumes that all line pieces or faces are defined using either a right-hand rotation or left-hand rotation everywhere.

In output/monitoring/surface[*]/ the following attributes can be set:

  • @name: Optional attribute to give a name to the output object.
  • @filename: Location of the input file defining the curve or surface. If left empty, the input has to be included in the body of the XML key.
  • @maxsplit [Default: "6"}]: Maximum element splitting level.
  • @threshold [Default: "1.0"]: Threshold for element splitting. This attribute is normalized by the grid spacing.
  • @details [Default: "true"]: Generate detailed binary output of the pressure distribution across the surface or curve. This option can be switched on or off by setting details to 1 or 0, respectively.
  • @forces [Default: "true"]: Calculate the total force across the surface or curve. This option can be switched on or off by setting forces to 1 or 0, respectively.
  • @moving [Default: "false"]: If this option is set to "true", the position of the monitoring object follows the moving object. By default the monitor point remains at a fixed position.
  • @tmin, @tmax, @dt, @nr: An output interval as explained in Section 26.2.

For illustration purposes, two examples are given. The following XML input uses the above 2-D example wedge.in and generates 1000 outputs between times 0 [s] and 100 [s]. The curve is defined by a simple triangle, which is automatically split in smaller line pieces by ComFLOW up to 7 levels. The surface is set to follow the moving object and both detailed plots and force calculations are requested.

<monitoring>
    <surface filename="input_files/wedge.in"
             tmin="0." tmax="100." dt=".1"
             moving="true" details="true" forces="true"
             maxsplit="7" threshold="1."  />
</monitoring>

Similarly one could use the 3-D example surface to generate high-frequency output at a given time interval:

<monitoring>
    <surface filename="input_files/box.in"
             tmin="50." tmax="60." dt=".001"
             moving="true" details="true" forces="true"  />
</monitoring>

19.4. Relative water height lines

Relative water height lines allow for the calculation of total water height along a line piece. These water height calculations are more accurate than simple fill boxes (see Section 19.5.1) since the interpolation method also takes into account the actual distribution of the liquid inside the grid cells by means of a piecewise linear reconstruction (PLIC).

Relative water height lines can be set to follow moving objects, e.g. ships. This allows for calculation of water heights in body-fixed coordinate system. When placing relative water height lines in the vicinity of solid (moving) objects, care has to be taken to keep a distance of at least one grid cell spacing from the object. This avoids the presence of numerical noise due to the cut-cell discretization of the object on the grid.

A relative water height line can be created by inserting a subkey /comflow/output/???? in the XML input file. The line piece is defined by the coordinates of start and end point. The ordering of these two points does not affect the calculated water height. The usual time and motion attributes can be set as well. The following example input defines two relative water height lines that both follow the moving object.

<monitoring>
    <relative_water_height>
        <line tmin="0." tmax="100." dt=".01" moving="true">
            <!-- xmin xmax ymin ymax zmin zmax -->
            -10. -6.  0. 0.    4.   7.
        </line>
        <line tmin="0." tmax="100." dt=".01" moving="true">
            <!-- xmin xmax ymin ymax zmin zmax -->
            -5.  -6.  0. 0.    3.   1.
        </line>
    </relative_water_height>
</monitoring>

The comments in the above example are ignored.

19.5. Boxes

19.5.1. Fill boxes

In some applications it can be useful to monitor the fill ratio of a small part of the domain. Fill boxes can be used to define box regions for which to calculate the total volume, total closed volume (due to solid objects) and the fill percentage of the remaining open area.

<boxes>
   <fill tmin="0." tmax="100." dt=".01" moving="true">
     <!-- xmin xmax ymin ymax zmin zmax -->
     -10. -6.  0. 0.    4.   7.
   </fill>
</boxes>

Fill boxes can also be used to calculate water heights in grid-aligned directions. By setting e.g. xmin and ymin equal to xmax and ymax and extending the box in the vertical direction, the fill box covers exactly one column of grid cells and therewith approximates the local water height. However, for accurate water height calculations it is strongly recommended to use relative water height lines (see Section 19.4), because these account better for the actual liquid distribution.

Although it is possible to define moving fill boxes, care should be taken at using this feature since fill boxes are always clipped to the grid, therewith possibly causing jumps in time. Again, for some applications relative water height lines may provide an alternative (see Section 19.4).

19.5.2. Force boxes

For simple force calculations on objects it may be sufficient to define a box region in which to integrate the pressure contributions on the solid object. Force boxes define a box region in the domain for which all pressure contributions on all closed cell segments are integrated in order to obtain the total force and moments that act on the geometry.

NB: Force boxes rely on the cell and face apertures to detect solid boundaries and cannot distinguish between different (moving) objects. For this reason it is important to make sure only 1 object is contained within the specified (moving) box region. For obtaining reliable force calculations on (parts of) solid (moving) objects that are close to each other, it is strongly recommended to define monitoring surfaces (see post_processing/monitor_surfaces) and to select the option @forces="true" for calculating the total force.

In simulations with (interactively) moving objects the force boxes can be set to follow the motion of the objects. Also after translation and rotation, the force box remains a box region and therefore its dimensions can change during the course of the simulation.

<boxes>
   <force tmin="0." tmax="100." dt=".01" moving="1">
     <!-- xmin xmax ymin ymax zmin zmax -->
     -10. -6.  -1. 1.    4.   7.
   </force>
</boxes>

19.5.3. Flux planes

Flux planes can be used to calculate the total fluid flow through a planar section. The orientation of the plane and the plane constant can be set by specifying the same values for either the X, Y or Z coordinate pairs. For example, the following input defines a flux plane at x=0.

<boxes>
   <flux tmin="0." tmax="100." dt=".01">
     <!-- xmin xmax ymin ymax zmin zmax -->
      0. 0. -10. 10. -20. 4.
   </flux>
</boxes>

Note that flux planes are snapped to the computational grid. Therefore, using the option @moving="true" can cause small discrete jumps in the output due to grid cell transitions of the moving flux plane. This option is therefore not recommended for general use.

19.6. Particle paths

Stream lines can be calculated by introducing particles in the flow. The settings for this feature can be specified in the key output/particles/. Particles can be placed in the domain at a given location and time instance after which the particle path is obtained by numerical time integration. This is either done by a first-order implicit discretization of the particle velocity or by Heun’s time integration method, which is second-order accurate in time.

Particles can be inserted as follows:

<particles>
   <particle method="2" tmin="1.2">
      <!-- x0 y0 z0 -->
      10.  5.  0.
   </particle>
   <particle tmin="2.0">
      <!-- x0 y0 z0 -->
      10.  5.  0.
   </particle>
</particles>

The option @method can be set to 1 or 2 for first-order or second-order approximation of the particle velocity. In the above example two particles are inserted in the flow at location \((10,5,0)\), first at time instance t=1.2 [s], then at time instance t=2.0 [s]. The attribute @tmin determines the insertion time of the particle as well as the starting point for post-processing output.

Note that once a particle has left the domain, the end of the particle path has been reached and no further output is generated.

19.7. HDF5 field data (special boxes)

In small parts of the domain, data of the pressure, water height and velocity can be stored at each time step. This can be necessary if the output of the simulation will be used for structural response calculations. Boxes can be defined such that for all cell centers enclosed by the box, the pressure (p), liquid fraction (fs) and velocity components (u, v, w) are written to a file. To prevent unnecessary data storage, a start and end point in time can be provided for each box.

The pressure, liquid fraction and optionally the velocities of all points contained in the boxes are stored in a different file every time step, starting at time point tmin and ending at time tmax as specified for each individual box.

The following example defines two special boxes. One box covers the entire flow domain and produces output during a small time interval at the start of the simulation. Another box is located in the outflow region of the domain and is used to produce output in a later stage of the simulation.

<boxes>
   <special tmin="0." tmax="0.1" dt="0.01" uvw="2">
     <!-- xmin xmax ymin ymax zmin zmax -->
      -Inf Inf -Inf Inf -Inf Inf
   </special>
   <special tmin="100." tmax="140." dt="0." uvw="2">
     <!-- xmin xmax ymin ymax zmin zmax -->
      400. 1000. -Inf Inf -Inf Inf
   </special>
</boxes>

Note that box regions are cropped to the domain, hence specifying Inf can be interpreted as being on the domain boundary and avoids the need of specifying the exact values.

The attribute @uvw determines the type of velocity approximation. By default, this option is set to 0 which means no velocity data is written to file. If it is set to 1, the velocities are interpolated towards the cell centers; if it is set to 2, the “raw” velocities (located at the right cell faces) are written to file.

The special box output is stored in the HDF5 file ${OUTPUT}/specialbox.h5. The contents of this file can be inspected by means of the HDFView utility, which can be downloaded here, but can also be imported in programs like MATLAB, as explained here, or in the open-source program Octave. The lay-out of the file contents is described in Section 28.2. Special box output can also be visualized in the MATLAB post-processor in the same manner as regular snapshot files.

Note

NB(1): Use this option with care, large amounts of data can be generated! NB(2): Special boxes cannot be used in regions of the grid containing local refinement. For these purposes it is recommended to use snapshot boxes instead (see Section 19.2).

19.8. Various output

During a ComFLOW simulation various other small output is written to file. Most of this information is stored at the time instances that coincide with the general print settings (see Section 19.1). A few exceptions are treated below.

19.8.1. Center of mass & moment of inertia

During simulations with moving objects, information can be generated about the center of mass and moment of inertia of the object. The output is stored in the ASCII file com.dat and the output interval can be controlled in the XML sub-key /comflow/output/commoi/ by means of the usual attributes, e.g.

<output>
   <commoi tmin="0." tmax="1000." dt="0.1">
</output>

19.8.2. CSR matrices

The matrices that are sent to the linear solver can be written to file for diagnostic purposes. The output interval can be controlled in the key output/matrix/ by means of the usual attributes, e.g.

<output>
   <matrix tmin="10." tmax="11." dt="0.1">
</output>

The resulting files matrix####.csr can be read by means of the MATLAB class CSRMatrix that is included in the ComFLOW distribution.