Export configuration

Enabling exporters

Configuring exporters in preCICE is really easy. To export the meshes of MySolver1 as vtu, add the following to the configuration of the participant:

<participant name="MySolver1">
    ...
    <export:vtu />
    ...
</participant>

This will automatically export all known meshes of MySolver1 as .vtu files to the working directory of the participant. If MySolver1 is a serial participant, then it will create a single .vtu file per export and mesh. If the solver runs in parallel, then every rank writes its local part of the mesh as a .vtu file in addition to a single .pvtu file, which allows to load the entire mesh.

Of course, this is only the data at the coupling surface. So the main purpose of this feature is to debug, not to analyze physical results.

Structuring exports

It is generally a good idea to structure these exports giving them a directory to export to:

<participant name="MySolver1">
    ...
    <export:vtu directory="precice-exports" />
    ...
</participant>

This tells preCICE to write all exports to a separate directory. The argument can be either an absolute or relative path.

Export frequency

The following two options allow to control the frequency of exports.

• every-n-time-windows="{integer}": Use this if you want to output only every x time steps. This is especially useful to reduce required disk space when dealing with large meshes and/or very long simulations.

• every-iteration="true": Use this if you are working with an implicit coupling scheme and are interested in the output for every coupling iteration. Be aware that this quickly produces a lot of exports.

File formats

preCICE supports various file formats to export to. These various formats have different purposes and capabilities.

VTK

<export:vtk />

The original VTK exporter exports to the legacy ASCII VTK format. As the format only supports serial participants, it exports to parallel VTU files if needed. Its intended use-case is to visualize coupling-meshes in Paraview.

VTU

<export:vtu />

The VTU exporter exports to the unstructured-grid XML format of VTK, namely VTU. Serial participants export meshes to .vtu files. Parallel participants export meshes as .vtu piece files and additionally create a .pvtu file. Use the latter file to load the entire mesh in Paraview. Its intended use-case is the visualization of coupling-meshes in Paraview.

VTU files tend to be slightly smaller than VTP files, but the connectivity information is less readable.

VTP

<export:vtp />

The VTP exporter exports to the polynomial XML format of VTK, namely VTP. Serial participants export meshes to .vtp files. Parallel participants export meshes as .vtp piece files and additionally create a .pvtp file. Use the latter file to load the entire mesh in Paraview. Its intended use-case is the visualization of coupling-meshes in Paraview.

VTP files tend to be slightly larger than VTU files, but the explicit connectivity information is easier to read.

CSV

<export:csv />

This exporter creates CSV files containing the vertex data of the meshes. Parallel participants will create one CSV file per rank. These CSV files use semicolon (;) as a delimiter and do not contain connectivity information.

The intended use-case of the exporter is quick debugging of pure coupling-data, which may be more useful when dealing with pseudo-meshes. It also simplifies post-processing using other software including python, R and spreadsheet applications.

The following example shows what the header of the CSV file looks like:

<data:scalar name="Temperature"/>
<data:vector name="Forces"/>

<mesh name="MyMesh1" dimensions="3">
  <use-data name="Temperature"/>
  <use-data name="Forces"/>
</mesh>

The resulting header of the CSV file looks as follows:

PosX;PosY;PosZ;Rank;Temperature;ForcesX;ForcesY;ForcesZ

These files can be loaded and merged using python and pandas:

def loadParallelCSV(name):
  import glob, pandas
  return pandas.concat([pandas.read_csv(name, sep=";") for name in glob.glob(f"{name}_*.csv")], ignore_index=True)

def loadParallelCSVSeries(name)
  import re, glob, pandas
  l = [(re.search("dt(\d+)_", s).group(1), s) for s in glob.glob(f"{name}.dt*_*.csv")]
  return pandas.concat([pandas.read_csv(file, sep=";").assign(dt=dt) for dt, file in l], ignore_index=True)

pointData       = loadParallelCSV("A-ExporterTwo.dt1")
pointDataSeries = loadParallelCSVSeries("A-ExporterTwo")

Visualization with ParaView

Loading series files

VTK, VTU, and VTP exporters write a .series file at the end of the simulation unless they are configured to export iterations. A series file loads the entire dataset and maps each export to its actual time. This allows you to open a series directly from the terminal, which can be convenient at times.

Applying displacements

If you use a static reference mesh with point displacements, you will see the points in the static reference domain. You may want to use the Warp By Vector filter to apply the displacements before continuing with the visualization.

Visualize

If you have not defined edges or triangles, the VTK/VTU/VTP files will only contain point data. You can visualize them in ParaView using either of:

• Point Gaussian representation - A quick and easy way to visualize the vertex positions as well as scalar data. Adjust the Gaussian Radius to reduce overlap. You might need to zoom-in to see the data (e.g., by clicking “Reset” in the camera controls toolbar).
• Glyph filter - A quick way to visualize vectorial data using arrows, or scalar data using scaled boxes or spheres. Note that more recent ParaView version use Arrow as default Glyph Type, which might be perpendicular in the 2D plane and therefore not visible by default. You might need to switch the type. Make sure to not use Rank as Scale Array, as Rank=0 for serial runs, leading to zero-sized glyphs.
• A Delaunay 2D filter to get a surface from the points. If your coupling surface is not XY-aligned, use the best fitting plane setting of the filter. If Delaunay 2D is not able to reconstruct a meaningful surface (i.e. in the case of a thin flap), Delaunay 3D may give a meaningful volume.