Input and output mesh file formats

GRUMMP has the capability to input and output two-dimensional meshes in user-defined formats. To take advantage of this feature, the user must create a file called user2d.template in the directory GRUMMP/src/IO_generator. This file is processed by the programs in2d_gen and out2d_gen to produce C++ functions which, respectively, read and write two-dimensional meshes with the format described in user2d.template. These functions are added to the GRUMMP two-dimensional mesh manipulation library, libGR_2D, the next time this library is remade. A default template file, default2d.template, is used if user2d.template does not exist. Step-by-step, then, the process for setting up user-defined file formats for two-dimensional meshes is:

  1. Edit GRUMMP/src/IO_generator/user2d.template.
  2. Return to the GRUMMP directory.
  3. Type make.
When data is read by the GRUMMP executables, conversion of the input connectivity data to an internal format is performed automatically. There are two valid ways to specify connectivity. First, the data file can provide both face-cell and face-vertex connectivity. Second, cell-vertex connectivity can be provided for the interior of the mesh along with boundary condition and vertex data for each boundary face. In either case, any redundant data is verified to ensure consistency.

The remainder of this section describes the format of user2d.template. On systems that have flex, in2d_gen and out2d_gen are not case sensitive; upper and lower case may be mixed indiscriminately. Systems using lex require lower case, because some lex implementations can not produce case insensitive parsers. configure will warn you if your system seems to be using lex.

The following description includes tokens in mixed case for readability. A ``^'' preceding a token indicates that it must begin a new line in the template file. ``Whitespace'' refers to any number of consecutive spaces or tabs within a line.

Figure 3.3: Orientation of boundary data in two dimensions.
\includegraphics[width=0.5\textwidth]{pics/bface2d}

An example template file (in fact, the default two-dimensional template, default2d.template) is shown in Figure 3.4.
Figure 3.4: Example template file for 2D I/O.
\begin{figure}\par\begin{list}{}{\setlength{\rightmargin}{\leftmargin}\setl...
...lls~verts
\par
bdryfaces:~face~bc~verts
\par
cells:~region\end{list}\end{figure}

Three-dimensional I/O templates are quite similar to two-dimensional templates, conceptually. Obviously, in this case there are three spatial coordinates, x, y and z. Also, faces, boundary faces, and internal boundary faces can now specify a vertC; cells can specify a vertD, a faceC and a faceD.

The orientation of cells and vertices around a face is such that, if the right hand rule is used to trace vertices A, B, and C, then one's thumb points towards cell B, as shown in Figure 3.5. For a boundary face, the orientation of the vertices is such that the interior of the domain is where cell B is in Figure 3.5.

Figure 3.5: Orientation of cells and vertices for a three-dimensional face.
\includegraphics[width=0.75\textwidth]{pics/face3d}

The default three-dimensional template (default3d.template) differs from its two-dimensional counterpart only in that the file suffix given is vmesh instead of mesh.

In both two and three dimensions, an alternative template file (mr[23]d.template) is also provided for output of meshes with internal boundaries; note that coarsen[23]d and meshopt[23]d can not currently read multi-domain files.

Carl Ollivier-Gooch 2017-07-20