CHILmesh: representing triangular, quadrangular and mixed-element (2D) meshes for advanced and automatic mesh generation for hydrodynamic domains.

Dominik Mattioli^1†, Ethan Kubatko^2
†Corresponding author

¹Penn State University
²Computational Hydrodynamics and Informatics Lab (CHIL), The Ohio State University

Releases

• 2026/04 0.1.1 - Honest hotfix: bug-fix release with regression tests, package data, and chilmesh.examples
• 2025/04/12 Python version of our code
• 2023/09/19 MATLAB code revisited; repo initiated
• 2017/08/01 Nascent MATLAB version of the code

Table of Contents

• Releases
• Installation
• Key Features
• Example Usage
• See also
• BibTeX
• Acknowledgements

Installation

Install the latest release from PyPI:

pip install chilmesh

Or install from source:

git clone https://github.com/domattioli/CHILmesh && cd CHILmesh
python -m venv .myenv
source .myenv/bin/activate
pip install -e .

Key Features

• Minimal user input, automatic generation.
• Support for triangular, quadrilateral, and mixed-element meshes.
• Finite Element Method (FEM)-based and geometric mesh smoothing and other topological quality-improvement functionality.
• Element quality evaluation (angular skewness) for quads & tris.
• Novel [layer-based conceptualization for 2D meshes.
  • MeshLayers.pdf
• .fort.14 file input/output for ADCIRC models
• API inspired by MATLAB’s delaunayTriangulation()

Example Usage:

# Load mesh
import matplotlib.pyplot as plt
import numpy as np
import chilmesh

# Load one of the bundled example meshes (no file paths required).
mesh = chilmesh.examples.annulus()
# Other built-ins: chilmesh.examples.donut(), .block_o(), .structured()

# Set up 2x3 subplot grid
fig, axs = plt.subplots(2, 3, figsize=(18, 10))
axs = axs.flatten()
fig.suptitle("Original vs Smoothed Mesh Comparison", fontsize=16)

# --- Original Mesh Plots ---
# 0. Original: Mesh + point/edge/element
_, ax = mesh.plot(ax=axs[0])
mesh.plot_point(1, ax=ax)
mesh.plot_edge(1, ax=ax)
mesh.plot_elem(1, ax=ax)
ax.set_title("Original: Mesh + Highlighted Entities")

# 1. Original: Layers
_, ax = mesh.plot_layer(ax=axs[1])
ax.set_title("Original: Mesh Layers")

# 2. Original: Quality
q0, _, stats0 = mesh.elem_quality( )
print( stats0 )
_, ax = mesh.plot_quality(ax=axs[2])
ax.set_title(f"Original: Quality Map (Median: {np.median(q0):.2f}, Std: {np.std(q0):.2f})")

# --- Smoothed Mesh Plots ---
# 3. Smoothed: Mesh + point/edge/element
mesh_smoothed = mesh.copy()
mesh_smoothed.smooth_mesh( method='fem', acknowledge_change=True )
_, ax = mesh_smoothed.plot(ax=axs[3])
mesh_smoothed.plot_point(1, ax=ax)
mesh_smoothed.plot_edge(1, ax=ax)
mesh_smoothed.plot_elem(1, ax=ax)
ax.set_title("Smoothed: Mesh + Highlighted Entities")

# 4. Smoothed: Layers
_, ax = mesh_smoothed.plot_layer(ax=axs[4])
ax.set_title("Smoothed: Mesh Layers")

# 5. Smoothed: Quality
q, _, stats = mesh_smoothed.elem_quality( )
print( stats )
_, ax = mesh_smoothed.plot_quality(ax=axs[5])
ax.set_title(f"Smoothed: Quality Map (Median: {np.median(q):.2f}, Std: {np.std(q):.2f})")

# Layout tidy
plt.tight_layout()
plt.subplots_adjust(top=0.9)  # leave space for suptitle
plt.show()
#fig.savefig("result.png", dpi=600, bbox_inches='tight')

The figure above is regenerated by pytest tests/test_readme_quickstart.py, which loads the bundled annulus, asserts geometric validity at every step (positive signed area, finite interior angles, complete layer cover, fort.14 roundtrip), runs the FEM smoother, re-validates, and writes the PNG. If the test passes, the image is current. Re-run it after any change that affects the visualization and commit the updated PNG.

Note: When mesh is mixed-element, connectivity (elem2vert adjacency) follows the format Node1-Node2-Node3-Node4, such that Node4 == Node3 for triangular elements.

See also / Downstream projects

MADMESHR is a downstream research project that builds on CHILmesh.

BibTeX:

DO Mattioli (2017). QuADMESH+: A Quadrangular ADvanced Mesh Generator for Hydrodynamic Models [Master's thesis, Ohio State University]. OhioLINK Electronic Theses and Dissertations Center. http://rave.ohiolink.edu/etdc/view?acc_num=osu1500627779532088

@mastersthesis{mattioli2017quadmesh,
  author       = {Mattioli, Dominik O.},
  title        = {{QuADMESH+}: A Quadrangular ADvanced Mesh Generator for Hydrodynamic Models},
  school       = {The Ohio State University},
  year         = {2017},
  note         = {Master's thesis},
  url          = {http://rave.ohiolink.edu/etdc/view?acc_num=osu1500627779532088}
}

• Read the pdf for free here

Acknowledgements

The following pieces of work inspired contributions to this repository:

• ADMESH
• See the rest of the citations in the thesis QuADMESH-Thesis.pdf
• Original work was funded by Aquaveo and contributed to by Alan Zundel.
• FEM Smoother paper
  • Inspiring MATLAB implementation
• Angle-Based Smoother paper
  • The MATLAB code was originally developed for a master's thesis research project (2015–2017) at The Ohio State University.