4.4 NekMesh modules

NekMesh is designed to provide a pipeline approach to mesh generation. To do this, we break up tasks into three different types. Each task is called a module and a chain of modules specifies the pipeline.

The figure below depicts how these might be coupled together to form a pipeline:

SVG-Viewer needed.

Figure 4.2: Illustrative pipeline of the NekMesh process.

On the command line, we would define this as:

NekMesh -m process1 -m process2 input.msh output.xml

Process modules can also have parameters passed to them, that can take arguments, or not.

NekMesh -m process1:p1=123:booleanparam input.msh output.xml

To list all available modules use the -l command line argument:

Available classes: 
  Input: dat: 
    Reads Tecplot polyhedron ascii format converted from Star CCM (.dat). 

and then to see the options for a particular module, use the -p command line argument:

Options for module detect: 
        vol: Tag identifying surface to process.

Note: Module names change when you use the -p option. Input modules should be preceded by in:, processing modules by proc: and output modules by out:.

4.4.1 Input modules

Input and output modules use file extension names to determine the correct module to use. Not every module is capable of reading high-order information, where it exists. The table below indicates support currently implemented.

Format Extension High-order


Gmsh msh

Only reads nodes, elements and physical groups (which are mapped to composites).

Nektar rea

Reads elements, fluid boundary conditions. Most curve types are unsupported: high-order information must be defined in an accompanying .hsf file.

Nektar++ xml

Fully supported.

PLY ply

Reads only the ASCII format..

Semtex sem

Reads elements and boundary conditions. In order to read high-order information, run meshpr session.sem > session.msh and place in the same directory as the session file.

Star-CCM+ dat

Star outputs plt file which currently needs to be coverted to ascii using Tecplot. Reads mesh only, only support for quads and triangles (2D) and hexes, prisms, tetrahedra (3D).

Star-CCM+ ccm

Reads start ccm format. Reads mesh only, only support for quads and triangles (2D) and hexes, prisms, tetrahedra (3D). Requires NEKTAR_USE_CCM option to be activated in cmake and then requires ccmio library to be compiled by user.

VTK vtk

Experimental support. Only ASCII triangular data is supported.

Note that you can override the module used on the command line. For example, Semtex session files rarely have extensions. So for a session called pipe-3d we can convert this using the syntax

NekMesh pipe-3d:sem pipe-3d.xml

Typically, mesh generators allow physical surfaces and volumes to contain many element types; for example a cube could be constructed from a mixture of hexes and prisms. In Nektar++, a composite can only contain a single element type. Whilst the converter will attempt to preserve the numbering of composites from the original mesh type, sometimes a renumbering will occur when a domain contains many element types. For example, for a domain with the tag 150 containing quadrilaterals and triangles, the Gmsh reader will print a notification along the lines of:

Multiple elements in composite detected; remapped: 
- Tag 150 => 150 (Triangle), 151 (Quadrilateral)

The resulting file therefore has two composites of IDs 150 and 151 respectively, containing the triangular and quadrilateral elements of the original mesh.

4.4.2 Output modules

The following output formats are supported:

Format Extension High-order


Gmsh msh

Curvature output is highly experimental.

Nektar++ xml

Most functionality supported.

VTK vtk

Experimental. Only ASCII triangular data is supported.

Note that for both Gmsh and VTK, it is highly likely that you will need to experiment with the source code in order to successfully generate meshes since robustness is not guaranteed.

The default for xml is into binary data which has been converted into base64. If you wish to see an ascii output you need to specify the output module option uncompress by executing:

MeshConvert Mesh.msh output.xml:xml:uncompress

In the rest of these subsections, we discuss the various processing modules available within NekMesh.

4.4.3 Extract surfaces from a mesh

To extract composite surfaces 2 and 3 from a mesh use the module extract module:

MeshConvert -m extract:surf=2,3 Mesh.xml output.xml

If you also wish to have the boundaries of the extracted surface detected add the detectbnd option

MeshConvert -m extract:surf=2,3:detectbnd Mesh.xml output.xml

4.4.4 Negative Jacobian detection

To detect elements with negative Jacobian determinant, use the jac module:

NekMesh -m jac Mesh.xml output.xml

To get a detailed list of elements which have negative Jacobians, one may use the list option:

NekMesh -m jac:list Mesh.xml output.xml

and to extract the elements for the purposes of visualisation within the domain, use the extract boolean parameter:

NekMesh -m jac:extract Mesh.xml MeshWithNegativeElements.xml

To turn off curvature associated with negative jacobians one can try to use the removecurveifsingular boolean parameter:

NekMesh -m jac:removecurveifsingular  Mesh.xml output.xml

This option will remove the high order curvature on prismatic faces with singular jacobians. This does not guarantee a non-singular mesh since it is possible for neighbouring element then to have singular jacobians. Multiple calls to the module might help with this scenario.

4.4.5 Spherigon patches

Where high-order information is not available (e.g. when using meshes from imaging software), various techniques can be used to apply a smoothing to the high-order element. In NekMesh we use spherigons, a kind of patch used in the computer graphics community used for efficiently smoothing polygon surfaces.

Spherigons work through the use of surface normals, where in this sense ‘surface’ refers to the underlying geometry. If we have either the exact or approximate surface normal at each given vertex, spherigon patches approximate the edges connecting two vertices by arcs of a circle. In NekMesh we can either approximate the surface normals from the linear elements which connect to each vertex (this is done by default), or supply a file which gives the surface normals.

To apply spherigon patches on two connected surfaces 11 and 12 use the following command:

NekMesh -m spherigon:surf=11,12 \ 
    MeshWithStraighEdges.xml MeshWithSpherigons.xml

If the two surfaces "11" and "12" are not connected, or connect at a sharp edge which is C0 continuous but not C1 smooth, use two separate instances of the spherigon module.

NekMesh -m spherigon:surf=11 -m spherigon:surf=12 \ 
    MeshWithStraighEdges.xml MeshWithSpherigons.xml

This is to avoid the approximated surface normals being incorrect at the edge.

If you have a high-resolution mesh of the surfaces 11 and 12 in ply format it can be used to improve the normal definition of the spherigons. Run:

NekMesh -m spherigon:surf=11,12:usenormalfile=Surf_11-12_Mesh.ply \ 
    MeshWithStraighEdges.xml MeshWithSpherigons.xml

This can be useful, for example, when meshing the Leading edge of an airfoil. Starting from a linear mesh (left figure) the spherigon patches curve the surface elements producing leading edge closer to the underlying geometry:


Figure 4.3: (a) Leading edge without spherigons, (b) Leading edge with spherigons

4.4.6 Periodic boundary condition alignment

When using periodic boundary conditions, the order of the elements within the boundary composite determines which element edges are periodic with the corresponding boundary composite.

To counteract this issue, NekMesh has a periodic alignment module which attempts to identify pairs of mutually periodic edges. Given two surfaces surf1 and surf2, which for example correspond to the physical surface IDs specified in Gmsh, and an axis which defines the periodicity direction, the following command attempts to reorder the composites:

NekMesh -m peralign:surf1=11:surf2=12:dir=y \ 
    -m peralign:surf1=13:surf2=14:dir=z Mesh.xml Mesh_aligned.xml

Here the surfaces with IDs 11 and 12 will be aligned normal to the y-axis and the surfaces 13 and 14 will be aligned normal to the z-axis.

Note that this command cannot perform magic – it assumes that any given edge or face lying on the surface is periodic with another face on the opposing surface, that there are the same number of elements on both surfaces, and the corresponding edge or face is the same size and shape but translated along the appropriate axis.

In 3D, where prismatic or tetrahedral elements are connected to one or both of the surfaces, additional logic is needed to guarantee connectivity in the XML file. In this case we append the orient parameter:

NekMesh -m peralign:surf1=11:surf2=12:dir=y:orient input.dat output.xml

Note: One of the present shortcomings of orient is that it throws away all high-order information and works only on the linear element. This can be gotten around if you are just doing e.g. spherigon patches by running this peralign module before the spherigon module.

4.4.7 Boundary layer splitting

Often it is the case that one can generate a coarse boundary layer grid of a mesh. NekMesh has a method for splitting prismatic and hexahedral elements into finer elements based on the work presented in [22] and [23]. You must have a prismatic mesh that is O-type – that is, you can modify the boundary layer without modifying the rest of the mesh.

Given n layers, and a ratio r which defines the relative heights of elements in different layers, the method works by defining a geometric progression of points

x =  x   + ark,   a = 2(1--r)-
 k    k-1             1- rn+1

in the standard segment [-1,1]. These are then projected into the coarse elements to construct a sequence of increasingly refined elements, as depicted in figure 4.4.

SVG-Viewer needed.

Figure 4.4: Splitting Ωst and applying the mapping χe to obtain a high-order layer of prisms from the macro-element.

To split a prism boundary layer on surface 11 into 3 layers with a growth rate of 2 and 7 integration points per element use the following command:

NekMesh -m bl:surf=11:layers=3:r=2:nq=7 MeshWithOnePrismLayer.xml \ 


Figure 4.5: (a) LE with Spherigons but only one prism layer for resolving the boundary layer, (b) LE with Spherigons with 3 growing layers of prisms for better resolving the boundary layer.

Note: You can also use an expression in terms of coordinates (x,y,z) for r to make the ratio spatially varying; e.g. r=sin(x). In this case the function should be sufficiently smooth to prevent the elements self-intersecting.

4.4.8 High-order cylinder generation

Generating accurate high-order curved geometries in Gmsh is quite challenging. This module processes an existing linear cylindrical mesh, with axis aligned with the z-coordinate axis, to generate accurate high-order curvature information along the edges.

NekMesh -m cyl:surf=2:r=1.0:N=5 LinearCylinder.xml HighOrderCylinder.xml

The module parameters are:

Note: The module could also be used to apply curvature along the interior of a hollow cylinder. However, there are no checks to ensure the resulting elements are not self-intersecting.

4.4.9 Surface extraction

Often one wants to visualise a particular surface of a 3D mesh. NekMesh supports extraction of two-dimensional surfaces which can be converted using XmlToVtk or similar programs for visualisation purposes, or combined with FieldConvert in order to extract the value of a 3D field on a given surface.

To extract a surface use the command:

NekMesh -m extract:surf=12,3,4 volume-mesh.xml surface-mesh.xml

where the integers are surface IDs to be extracted.

An optional arguemnt of detectbnd can be added to identify the boundary composites as part of the surface extraction.

4.4.10 Linearisation

The ability to remove all the high-order information in a mesh can be useful at times.

To do this in NekMesh use the command:

NekMesh -m linearise high-order-mesh.xml linear-mesh.xml

The output will contain only the linear mesh information, all curved information is removed.

4.4.11 Extracting interface between tetrahedra and prismatic elements

When the mesh is three-dimensional and comprised of a prismatic boundary layer with tetrahedra in the interior of the domain, this module extracts the prismatic elements only, and constructs a boundary region for the interface between the tetrahedra and prisms. This is useful in, for example, the study of aortic flows, where the prismatic boundary layer can be extracted and refined to study unsteady advection-diffusion problems on a more refined grid inside the boundary layer.

To use this module you therefore use the command:

NekMesh -m extracttetprisminterface input.xml output.xml

There are no configuration options for this module, as it is highly specific to a certain class of meshes.

4.4.12 Boundary identification

Some mesh formats lack the ability to identify boundaries of the domain they discretise. NekMesh has a rudimentary boundary identification routine for conformal meshes, which will create a composite of edges (2D) or faces (3D) which are connected to precisely one element. This can be done using the detect module:

NekMesh -m detect volume.xml volumeWithBoundaryComposite.xml

4.4.13 Scalar function curvature

This module imposes curvature on a surface given a scalar function z = f(x,y). For example, if on surface 1 we wish to apply a surface defined by a Gaussian z = exp[-(x2 + y2)] using 7 quadrature points in each direction, we may issue the command

NekMesh -m scalar:surf=1:nq=7:scalar=exp\(x*x+y*y\) mesh.xml deformed.xml

Note: This module makes no attempt to apply the curvature to the interior of the domain. Elements must therefore be coarse in order to prevent self-intersection. If a boundary layer is required, one option is to use this module in combination with the splitting module described earlier.