What This Tool Does

This code analyzes a volume mesh, checking for topological validity,
positive cell volumes, size ratio for adjacent cells, dihedral angles,
and distortion of quadrilateral faces.  Also, mesh length scale
perpendicular to the surface and along the surface are assessed.
Finally, if a Pointwise nmb file and the Pointwise GEODE library are
available, the distance from mesh points that should be on the geometry
to the actual geometry is assessed.

Much of the code is multi-threaded for speed (since the assessments are
embarassingly parallel, this is easy to do safely).  Also, to the extent
possible, the code operates on data streamed from disk rather than
reading the entire mesh into memory at once.

The topology checks are the biggest user of memory, because those checks
work by trying to match up the two copies of a triangular or
quadrilateral face.  Before beginning this process, an estimate of
required memory is done.  If this requirement is too large a fraction of
machine memory, a slower, less memory intensive variant of the algorithm
is invoked.

Mesh I/O is done using a plug-in architecture.  See Mesh-Readers.txt for
more information. 

How to Build

This package uses an autoconf-based build system.

You can run autoconf if you wish, but this isn't strictly necessary, as
a configure script is also included.

Options to configure, in addition to the standard ones:

  --enable-debug builds without optimization and with debugging enabled.

  --with-geode=/dir/for/Pointwise/GEODE/kernel
  --with-geode-arch=arch
       
       The Pointwise GEODE kernel, if available, can be used to check
       the projection of surface mesh points to the actual geometry
       (see below for usage).

       These two options must be supplied together.  Include files for
       GEODE must be in /dir/for/Pointwise/GEODE/kernel/include, and
       GEODE libraries must be in
       /dir/for/Pointwise/GEODE/kernel/lib/arch.

After you run configure, run make (and optionally make install).

How to Run

analyzeVolMesh requires a file type indicator and a base file name.  The
file type indicator can be vtk for a legacy (ASCII) file, or ugrid for
UGRID file.  For UGRID files, the UGRID file type specifier (b8, lb8,
etc) must be supplied as the last argument.  For example,

analyzeVolMesh vtk myMesh

This will read a VTK file called myMesh.vtk



analyzeVolMesh ugrid myOtherMesh b8

This will read a UGRID file called myOtherMesh.b8.ugrid.  At this point,
only four-byte integers are handled in UGRID files, even though there
are variants of the UGRID format that provide eight byte integers.


analyzeVolMesh ugrid myOtherMesh -nmb myGeometry.nmb b8

Same as above, but also checks distance from surface mesh points from
the geometry.



Output

The mesh analyzer produces four files:

1.  A VTK file (legacy ASCII format) that gives information associated
with each surface point:

  - The distance to the nearest interior point
  - The distance to the nearest point on the surface
  - The projected distance to the geometry defined in the .nmb file (if
    specified)
  - The surface ID in the geometry onto which each point is projected.

2. A file, readable by gnuplot, that quantifies non-planarity of
quadrilaterals in the mesh. (...-distort.dat).

3. A file, readable by gnuplot, that gives histograms of size ratio for
adjacent cells, arranged by the types of cells (tet-tet size ratio is
separate from tet-prism size ratio, and so on).  This file also includes
the total number of faces separating each pair of cell types.  Columns
are labeled in the file.

4. A file, readable by gnuplot, that gives histograms of dihedral and
face angles.

In the directories gnuplot-scripts and python-scripts, you will find the
gnuplot and paraview script files used to produce the figures in the
2018 AIAA SciTech paper analyzing meshes from the First AIAA Geometry
and Mesh Generation Workshop / Third AIAA High-Lift Prediction Workshop.


Reference

For more information, including mathematical formulations of various
quantities computed by the code and mentioned above, please see:

Carl F. Ollivier Gooch. "Analysis of Unstructured Meshes from GMGW-1 /
HiLiftPW-3", 2018 AIAA Aerospace Sciences Meeting, AIAA SciTech Forum,
(AIAA 2018-0132) https://doi.org/10.2514/6.2018-0132.

A PDF of this paper is included in the docs folder.

If you find this tool helpful and use it in your own work, please cite
this paper, as noted above.