Mesh Tools Overview

Table of Contents

• Mesh Generator Scripts
  • 2d_quad_circle.py
  • 2d_quad_onion.py
  • 2d_quad_rect.py
  • 2d_quad_ring.py
  • 2d_tria_rect.py
  • 3d_hexa_cube.py
• The mesh-extruder tool
• The mesh-indexer tool
• The mesh-partitioner tool
• The mesh-validator tool
• The mesh2vtk tool
• The mesh2eps tool
• The mesh2svg tool
• The mesh2tri tool
• The tri2mesh tool

This page gives an overview over the mesh-file related tools and scripts that can be found in the tools/mesh_tools directory.

Mesh Generator Scripts

There exist a few Python scripts that can be used to generate FEAT 3 mesh-files for some simple 2D and 3D domains. Please check the documentation of the scripts for details.

2d_quad_circle.py

Creates a 2D quadrilateral mesh that discretizes a circle domain with 4*N+1 quadrilateral elements, which looks roughly like this:

           .
        ./'|'\.
      ./'  |  '\.
    ./'  ./'\   '\.
  ./'  ./'   '\.  '\.
 +----+         +----+
  '\.  '\.   ./'  ./'
    '\.  '\./'  ./'
      '\   |  ./'
        '\.|./'
           '

2d_quad_onion.py

Creates a 2D quadrilateral mesh that discretizes a rectangular domain with 4*N+1 quadrilateral elements, which (for N=2) looks roughly like this:

 +-------------------+
 |'\.             ./'|
 |   +-----------+   |
 |   |'\.     ./'|   |
 |   |   +---+   |   |
 |   |   |   |   |   |
 |   |   +---+   |   |
 |   |./'     '\.|   |
 |   +-----------+   |
 |./'             '\.|
 +-------------------+

2d_quad_rect.py

Creates a 2D quadrilateral mesh that discretizes a rectangular domain with M*N quadrilateral elements. This script offers a wide variety of element sizing choices that also allow for the generation of anisotropic meshes, e.g.:

 +-----+--------------------+-----+
 |     |                    |     |
 +-----+--------------------+-----+
 |     |                    |     |
 |     |                    |     |
 +-----+--------------------+-----+
 |     |                    |     |
 |     |                    |     |
 |     |                    |     |
 +-----+--------------------+-----+

2d_quad_ring.py

Creates a 2D quadrilateral mesh that discretizes a ring domain with M*N quadrilateral elements.

2d_tria_rect.py

Creates a 2D triangular mesh that discretizes a rectangular domain with 2*M*N quadrilateral elements. This script is the triangular version of the 2d_quad_rect.py script, which subdivides each quadrilateral into 2 triangles.

3d_hexa_cube.py

Creates a 3D hexahedral mesh that discretizes a cuboid domain with M*N*L hexahedral elements.

The mesh-extruder tool

This tool can be used to create a 3D hexahedral mesh from a 2D quadrilateral mesh by extruding it in Z direction thus forming a "2.5D" mesh, which also includes an extrusion of the 2D charts that were used to parameterize the 2D input mesh. The 3D mesh can optionally also be rotated and translated by specifying an origin, an offset and a set of yaw-pitch-roll rotation angles given in revolutions

This tool accepts the following command line parameters:

• --in <input-meshfiles...>
  Mandatory: Specifies the 2D quadrilateral input mesh file(s).
• --out <output-meshfile>
  Mandatory: Specifies the 3D hexahedral output mesh file.
• --z-list <z_0> <z_1> ... <z_n>
  Mandatory: Specifies the ascending list of Z-coordinates at which the 3D mesh is to be sliced, where the first and the last entry in the list specify the total Z-extend of the 3D mesh. Mutually exclusive with --z-range.
• --z-range <z-min> <z-max> <n>
  Mandatory: Specifies the Z-coordinate range and the number of slices in Z-direction. Mutually exclusive with --z-list.
• --z-names <name-min> <name-max>
  Mandatory: Specifies the names for the Z-boundary mesh-parts.
• --origin <x> <y>
  Optional: Specifies the 2D transformation origin. Default to 0, 0.
• --offset <x> <y> <z>
  Optional: Specifies the 3D transformation offset. Default to 0, 0, 0.
• --angles <yaw> <pitch> <roll>
  Optional: Specifies the 3D transformation angles in revolutions. Default to 0, 0, 0.

The optional rigid body transformation consists of the origin vector v, the offset vector w as well as a 3D rotation matrix R, which is given by the yaw-pitch-roll angle triplet, which define the following transformation mapping:

\[ x \mapsto w + R \cdot(x - v)\]

Attention

The yaw-pitch-roll angles are given in revolutions (aka rotations aka full turns) rather than radians or degrees to avoid angles with a large number of digits for commonly used rotations. Note: 1 revolution = 360 degrees = 2π radians

Examples:
The following call creates a 3D unit cube mesh with 1 hexahedral element by extruding the 2D unit-square mesh:

mesh-extruder --in unit-square-quad.xml --out unit-cube-hexa.xml --z-range 0 1 1 --z-names bnd:f bnd:n

The following call creates a 3D cylinder domain with 3 slices in Z-direction from the 12-quad unit-circle mesh, with its center translated to (0,0,0) and rotated by 45 degrees (=1/8 revolution) around the X-axis:

mesh-extruder --in unit_circle_quad_12.xml --out cylinder_tilted.xml --z-list 0.0 0.1 0.9 1.0 --offset 0 0 -0.5 --angles 0.125 0 0

The mesh-indexer tool

This tool can be used to create a FEAT mesh file from a set of vertex coordinate and vertices@element indices text files. This is especially helpful if one needs to create a FEAT mesh file from some other mesh file format and if no other tool chain exists that could make that conversion possible in a more convenient way.

This tool accepts the following command line parameters:

• --out <output-meshfile>
  Mandatory: Specifies the filename of the FEAT 3 output mesh file.
• --shape <shape>
  Mandatory: Specifies the shape of the mesh to be generated. Must be one of the following:
  • h2 : Hypercube<2> mesh with 2D coordinates
  • h3 : Hypercube<3> mesh with 3D coordinates
  • h23 : Hypercube<2> mesh with 3D coordinates
  • s2 : Simplex<2> mesh with 2D coordinates
  • s3 : Simplex<3> mesh with 3D coordinates
  • s23 : Simplex<2> mesh with 3D coordinates
• --vtx <filenames...>
  Mandatory: Specifies the name(s) of the input text file(s) that contain the vertex coordinates. Each line of this file should contain the coordinate tuple (separated by spaces) of a single vertex and the number of coordinates must match the mesh shape specified by --shape. Empty lines and lines beginning with the hash character '#' are ignored.
• --idx <filenames...>
  Mandatory: Specifies the name(s) of the input text file(s) that contain the 0-based vertices@element indices. Each line of this file should contain the vertex-index tuple (separated by spaces) of a single element and the number of indices must match the mesh shape specified by --shape. The indices are expected to be given in the correct order according to the FEAT 3 numbering, see meshfile_shape_numbering for details. Empty lines and lines beginning with the hash character '#' are ignored.
• --bnd
  Specifies that a single mesh part named 'bnd' for the entire boundary is to be generated.
• --parts <name1> <formula1> [<name2> <formula2> ...]
  Specifies a set of name-formula argument pairs which are used to generate meshparts by using the FEAT::Geometry::ParsedHitTestFactory class. The first component of each pair specifies the name for the mesh part, whereas the second component specifies the formula in x,y,z coordinates, which is to be used for the hit test of the mesh part. A vertex or edge/face/cell will be contained in the meshpart if the formula evaluates to a positive value in its coordinates or midpoint coordinates, respectively.

Attention

Please note that the --parts option can only be used if FEAT is configured and linked against the 'fparser' third-party library. Also, it is highly recommended to enclose each formula in a pair of double-quotation marks to ensure your command line interpreter doesn't get confused by more complex formulae.

The number of vertex coordinates files passed to the --vtx argument must always be equal to the number of element indices files passed to the --idx argument, since these always form a pair of vertices-elements relations.

This tools offers the possibility to join several meshes into a single meshes by specifying a set of multiple vertices-indices file pairs. In this case, the indices of the i-th index file correspond to the vertices given in the i-th vertex coordinate file.

Furthermore, this tool automatically removes duplicate vertices as well as orphan vertices, i.e. vertices which are not referenced by any element. Duplicate vertices usually appear when two or more meshes are joined together, whereas orphan vertices appear when one manually removes elements.

Examples:
The following call creates a 2D quadrilateral mesh from the vertices given in vertices.txt and the vertex@element indices given in elements.txt along with a single mesh-part named 'bnd' for the entire boundary:

mesh-indexer --out mesh.xml --shape h2 --vtx vertices.txt --idx elements.txt --bnd

The following call creates a 3D tetrahedral mesh that is obtained by joining the two meshes which are given by the vertices-elements pairs verts_a.txt + elems_a.txt and verts_b.txt + elems_b.txt, i.e. elems_a.txt contains indices of the vertices in verts_a.txt and elems_b.txt contains indices of the vertices verts_b.txt:

mesh-indexer --out mesh.xml --shape s3 --vtx verts_a.txt verts_b.txt  --idx elems_a.txt elems_b.txt

The mesh-partitioner tool

This tool can be used to create a partitioning file for a given mesh file, which is then saved as a separate mesh file and which can be passed to MPI parallel applications in addition to the original mesh file to ensure that these applications picks one of the pre-computed partitionings instead of applying a partitioner at simulation time.

Attention

Please note that this tool can only be really useful if FEAT was configured and linked against the ParMETIS and/or Zoltan libraries, because FEAT does not provide any 'real' partitioners by its own except for a very experimental genetic partitioner that should not be used for real world use cases. In consequence, this tool must be compiled with MPI as both of these libraries require MPI.

This tool allows you to specify the number of desired partitions/patches independently of the number of MPI processes that this tool is run with, however, not all MPI processes may be used to run the partitioner if the workload is too small to distribute over all MPI processes.

This tool allows you to specify the refinement level of the mesh that is to be partitioned, if the unrefined mesh stored in the mesh file that you want to partition is too coarse for the number of patches that you want to create. The chosen partitioning level is then also written to the output file and the PartiDomainControl will also refine the mesh to the required level if it chooses to select the corresponding partitioning.

By default, the partitioning is named 'auto', which tells the PartiDomainControl, which is used to read in the partition mesh file, that the corresponding partitioning can be chosen automatically if the number of MPI processes matches the number of patches in the partitioning. If you choose a different name for the partitioning, you will have to tell the PartiDomainControl explicitly that you want to use that particular partitioning by supplying its name to the '–part-extern-name' command line parameter of the PartDomainControl object. Unless you indent to try out different partitionings for the same number of patches, it is recommended to simply leave the partition name as 'auto'.

By default, this tool creates the dual graph for the partitioner based on the facet-adjacency of the elements, however, you can also specify that the dual graph is to be defined based on the vertex-adjacency of the elements. The former one usually results in nicer partitionings, but you might want to try out the vertex-based adjacency if the facet-based element adjacency does not yield satisfactory results for the mesh that you are trying to partition.

If you want to visualize the partitioning created by this tool, you can simply use the 'mesh2vtk' tool and supply both the input mesh file as well as the partitioning mesh file written by this tool as input mesh files and the mesh2vtk tool will write out the partitioning as a cell variable in the resulting VTK file. If you have created the partitioning on a refinement level greater than 0, you also have to tell the mesh2vtk tool to write out the refined mesh on at least the same level to visualize the partitioning because it is not available on lower refinement levels, of course.

This tool supports the following command line parameters:

• --mesh <meshfile>
  Mandatory: Specifies the name of the input mesh file to be partitioned.
• --out <partition-file>
  Mandatory: Specifies the name of the output partition mesh file.
• --parts <n>
  Mandatory: Specifies the number of partitions/patches to create.
• --dual-by-verts
  Optional: Specifies that the dual graph is to be computed by vertices rather than by facets.
• --level <n>
  Optional: Specifies the mesh partitioning level; defaults to 0.
• --name <name>
  Optional: Specifies the name of the partitioning; defaults to 'auto'.
• --prio <priority>
  Optional: Specifies the priority of the partitioning; defaults to 1.
• --no-2lvl
  Optional: Specifies that the 2-level partitioner should not be used.
• --genetic <time-init> <time-mutate>
  Optional: Specifies that the genetic partitioner should be used. This partitioner is highly experimental and should not be used by mere mortals like you.
• --no-parmetis
  Optional: Specifies that the ParMETIS partitioner should not be used.
• --no-zoltan
  Optional: Specifies that the Zoltan partitioner should not be used.

The mesh-validator tool

This tool performs some basic sanity checks on a given mesh file to identify orphaned entities and other invalid adjacency combinations. Please note that this tool is very basic and does not offer any sophisticated checks (yet), but it can still be useful if one has created or modified a mesh file manually or via some custom script or conversion tool.

The mesh2vtk tool

This tool converts a mesh from the FEAT 3 mesh file format to a corresponding VTK format, which currently always corresponds the XML-based VTU file format for unstructured meshes. This tool can optionally also apply a rigid body transformation given by an origin-angles-offset tuple.

This tool accepts the following command line parameters:

• --mesh <filenames...>
  Mandatory: Specifies the filenames of the input mesh files in FEAT 3 mesh file format. Typically, one only specifies a single filename here, unless the information (e.g. charts and root mesh) is split up across several files.
• --vtk <filename>
  Optional: Specifies the filename of the output VTK/VTU file. If not given, the name of the first input mesh file is used, but with the extension .vtu instead of .xml.
• --level <lvl_max> [<lvl_min>]
  Optional: Specifies the minimum and maximum refinement level of the mesh for which the VTK files are to be written. If not given, on the input level (0) is processed.
• --origin <x> [<y> [<z>]]
  Optional: Specifies the translation origin, which is subtracted before applying the rotation matrix. If not given, all origin coordinates are set to 0.
• --angles <angle> (2D only)
  
• --angles <yaw> <pitch> <roll> (3D only)
  Optional: Specifies the rotation angle (2D) or the yaw-pitch-roll angles (3D) for the rotation matrix. If not given, all angles are set to 0. Note: All angles are given in revolutions (aka rotations aka full turns) rather than radians or degrees; 1 revolution = 360 degrees = 2π radians.
• --offset <x> [<y> [<z>]]
  Optional: Specifies the translation offset, which is subtracted after applying the rotation matrix. If not given, all offset coordinates are set to 0.
• --no-adapt
  Optional: Disables the adaption of the mesh boundary based on the charts stored in the mesh file.
• --no-dist
  Optional: Disables the automatic computation of the distance to each chart stored in the mesh file.
• --no-proj
  Optional: Disables the automatic computation of the projection fields to each chart stored in the mesh file.
• --no-volume
  Optional: Disabled the automatic computation of the cell volumes.
• --hit-test <name1> <formula1> [<name2> <formula2> ...]
  Specifies a set of name-formula argument pairs which are used to generate meshparts by using the FEAT::Geometry::ParsedHitTestFactory class. The first component of each pair specifies the name for the mesh part, whereas the second component specifies the formula in x,y,z coordinates, which is to be used for the hit test of the mesh part. A vertex or edge/face/cell will be contained in the meshpart if the formula evaluates to a positive value in its coordinates or midpoint coordinates, respectively.

Attention

Please note that the --hit-test option can only be used if FEAT is configured and linked against the 'fparser' third-party library. Also, it is highly recommended to enclose each formula in a pair of double-quotation marks to ensure your command line interpreter doesn't get confused by more complex formulae.

The mesh2eps tool

This tool converts a 2D triangular or quadrilateral mesh from the FEAT 3 mesh file format to an encapsulated post-script (EPS) file, so that it may be included as a vector graphic in e.g. a LaTeX document.

This tool accepts the following command line parameters:

• --mesh <filenames...>
  Mandatory: Specifies the filenames of the input mesh files in FEAT 3 mesh file format. Typically, one only specifies a single filename here, unless the information (e.g. charts and root mesh) is split up across several files.
• --eps <filename>
  Optional: Specifies the filename of the output EPS file. If not given, the name of the first input mesh file is used, but with the extension .eps instead of .xml.
• --level <lvl_max> [<lvl_min>]
  Optional: Specifies the minimum and maximum refinement level of the mesh for which the EPS files are to be written. If not given, on the input level (0) is processed.
• --box <width> <height>
  Specifies the bounding box of the figure in millimeters. If not given, a bounding box of 100 x 100 millimeters is used.
• --stroke <width>
  Specifies the stroke width of the edges in millimeters. If not given, a stroke width of 0.1 millimeters is used.
• --extra <offset>
  Specifies the extra offset of the figure in millimeters. If not given, an offset of 0.5 millimeters is used.
• --no-adapt
  Optional: Disables the adaption of the mesh boundary based on the charts stored in the mesh file.

The mesh2svg tool

This tool converts a 2D triangular or quadrilateral mesh from the FEAT 3 mesh file format to a scalable vector graphics (SVG) file, which can be either displayed directly in an internet browser or converted to another vector graphics format such as EPS or PDF via some vector graphics application like e.g. Inkscape.

This tool accepts the following command line parameters:

• --mesh <filenames...>
  Mandatory: Specifies the filenames of the input mesh files in FEAT 3 mesh file format. Typically, one only specifies a single filename here, unless the information (e.g. charts and root mesh) is split up across several files.
• --svg <filename>
  Optional: Specifies the filename of the output SVG file. If not given, the name of the first input mesh file is used, but with the extension .svg instead of .xml.
• --level <lvl_max> [<lvl_min>]
  Optional: Specifies the minimum and maximum refinement level of the mesh for which the EPS files are to be written. If not given, on the input level (0) is processed.
• --box <width> <height>
  Specifies the bounding box of the figure in millimeters. If not given, a bounding box of 100 x 100 millimeters is used.
• --stroke <width>
  Specifies the stroke width of the edges in millimeters. If not given, a stroke width of 0.1 millimeters is used.
• --extra <offset>
  Specifies the extra offset of the figure in millimeters. If not given, an offset of 0.5 millimeters is used.
• --no-adapt
  Optional: Disables the adaption of the mesh boundary based on the charts stored in the mesh file.

The mesh2tri tool

This tool converts a mesh from the FEAT 3 mesh file format to the legacy FEATFLOW 1/2 TRI mesh file format.

This tool accepts the following command line parameters:

• --mesh <filenames...>
  Mandatory: Specifies the filenames of the input mesh files in FEAT 3 mesh file format. Typically, one only specifies a single filename here, unless the information (e.g. charts and root mesh) is split up across several files.
• --tri <filename>
  Optional: Specifies the filename of the output TRI file. If not given, the name of the first input mesh file is used, but with the extension .tri instead of .xml.
• --level <lvl_max> [<lvl_min>]
  Optional: Specifies the minimum and maximum refinement level of the mesh for which the TRI files are to be written. If not given, on the input level (0) is processed.
• --knpr [<mesh-part-names...>]
  Specifies how the nodal property array KNPR is to be defined.
  If not given, then the entire nodal property array is formatted to 0.
  If given without any mesh-part names, then the nodal property is set to 0 for all interior vertices and to 1 for all boundary vertices.
  If at least one mesh-part name is given, then all vertices belonging to the first mesh-part get the nodal property 1, all vertices belonging to the second mesh-part get the nodal property 2, etc., and all remaining vertices get the nodal property 0.
  If multiple mesh-parts are to be combined so that all their vertices belong to the same nodal property group, then you can specify that group of mesh-parts by specifying their names in a double-quoted string, e.g.

    --knpr bnd:l "bnd:t bnd:b" bnd:r
  

  will yield 3 nodal property groups: bnd:l -> 1, bnd:t -> 2, bnd:b -> 2, bnd:r -> 3, the rest -> 0

The tri2mesh tool

This tool converts a 3D hexahedral mesh from the legacy FEATFLOW 1/2 TRI mesh file format to the FEAT 3 mesh file format.

This tool has a fixed command line argument structure:

tri2mesh <prjfile> <meshfile> [<scale>]

where

• <prjfile> is the mandatory filename of the input PRJ file
• <meshfile> is the mandatory filename of the output FEAT 3 mesh file
• <scale> is the optional scaling factor for the coordinates

Attention

This tool must be executed in the file.prj directory, as no folder voodoo takes place internally.

Todo:

Reimplement this tool in a less quick'n'dirty fashion...

Author

Peter Zajac