Fast 2D mesh processing, smoothing, and analysis for triangular, quadrilateral, and mixed-element meshes. Intended for hydrodynamic domains.

Dominik Mattioli^1†, Ethan Kubatko^2
†Corresponding author | ¹Unaffiliated | ²Ohio State University (CHIL)

MATLAB users: This Python library is the actively-developed successor to the original MATLAB codebase. The original (no longer maintained) is at src/@CHILmesh/CHILmesh.m and on MathWorks.

The stable backbone for hydrodynamic mesh tooling. Sibling projects ADMESH, ADMESH-Domains, and QuADMesh build on top of it.

• Pythonic API — from chilmesh import Mesh; backwards-compatible CHILmesh alias preserved.
• C++ acceleration, bit-identical output — half-edge extension is ~24× faster than pure Python on full init, verified bit-for-bit by 36 cross-backend equivalence tests.
• One interface for all topologies — triangles, quadrilaterals, and mixed meshes share the same call surface.
• Stable v1.x API — sibling projects can pin chilmesh>=1.0,<2.

pip install chilmesh                        # PyPI
uv pip install chilmesh                     # uv
conda install -c conda-forge chilmesh       # conda-forge (pending)
pip install -e .                            # from source

from chilmesh import Mesh

mesh = Mesh.read_from_fort14("ocean.14")
mesh.smooth_mesh(method="fem", acknowledge_change=True)
quality, angles, stats = mesh.elem_quality()
mesh.plot_quality()

The legacy chilmesh.CHILmesh import is preserved for backward compatibility. Built-in fixtures live at chilmesh.examples.{annulus, donut, block_o, structured}(). See examples/ for runnable scripts.

• Fast — full init + quality analysis on a 98,365-element mesh in ~1.7 s (4.6× faster than v0.2.0)
• Mixed-element — triangles, quads, and mixed meshes share one API
• Smoothing — Balendran direct FEM, Zhou-Shimada angle-based, and ADMESH Spring-Based Truss
• Analysis — element quality, interior angles, layer-based skeletonization (medial axis)
• I/O — ADCIRC .fort.14 and SMS Aquaveo .2dm read/write
• Spatial queries — point-in-element, k-nearest vertices, radius search at O(log n)
• Mesh alterations — insert_vertex, coord moves, advancing-front element addition; full mutation suite tracked in #94
• ADMESH-Domains integration — from_admesh_domain() adapter

_{Figure 1. Scale demo on WNAT_Hagen (52,774 vertices · 98,365 elements). plot_quality() renders per-element skew quality; plot_quality_histogram() emits the matched-colormap distribution beneath. Reproduce: python scripts/generate_wnat_showcase.py.}

Reference workload: WNAT_Hagen (52,774 vertices · 98,365 elements). Median of 3 trials. v1.0.0 backends are output-equivalent — the C++ extension produces bit-identical skeletonization layers to Python, verified by tests/test_backend_equivalence.py.

C++ is ~24× faster than Python on full init. ‡ MATLAB v0.1.0 measured under GNU Octave 8.4 — treat as the original-algorithm baseline, not a MATLAB-vs-Octave claim. † Rust (v0.4.0) skeletonization is incomplete (#163); its full-init figure reflects a partial peel. Full methodology and raw data: docs/BENCHMARK.md.

Python, C++, and the original MATLAB/Octave implementation all produce identical n_layers (medial-axis skeletonization) across the ADMESH-Domains catalog, from 557 to 132k vertices. Identical connectivity + points are fed to both implementations; only the layering algorithm is compared.

Three algorithms — each preserves boundary nodes, leaves topology unchanged, and accepts mixed-element meshes.

References.

• Balendran (1999). A direct smoothing method for surface meshes. Proc. 8th IMR, pp. 189–193.
• Zhou & Shimada (2000). An angle-based approach to two-dimensional mesh smoothing. Proc. 9th IMR, pp. 373–384.
• Conroy et al. (2012). ADMESH: An advanced, automatic unstructured mesh generator for shallow water models. doi:10.1007/s10236-012-0574-0.

pip install chilmesh gives you the pure-Python implementation — zero compiled dependencies, runs everywhere, and is the canonical reference every other backend is validated against. The C++ extension is the high-performance opt-in: same algorithms, bit-identical output, ~24× faster on full init.

import chilmesh

chilmesh.backend_info()
# {'available': ['cpp', 'python'],
#  'selected': 'cpp',
#  'versions': {'cpp': '0.6.0.dev0', 'python': '1.1.0'}}

Force a specific backend with CHILMESH_BACKEND (python or cpp). When unset, the fastest available is picked. Pre-built binary wheels (manylinux / macOS / Windows) via cibuildwheel are planned — see docs/ for build-from-source instructions.

python examples/01_quickstart.py        # load, stats, plot
python examples/02_fort14_roundtrip.py  # fort.14 read/write
python examples/03_smoothing.py         # angle-based smoother
python examples/04_spatial_queries.py   # find_element, radius search, k-nearest

chilmesh info mesh.fort.14                                      # stats
chilmesh convert mesh.2dm mesh.fort.14                         # format conversion
chilmesh smooth mesh.fort.14 -o out.fort.14 --method fem       # smooth in-place
chilmesh plot mesh.fort.14 -o mesh.png --quality               # render

Also available as python -m chilmesh. Each subcommand has --help.

CHILmesh is the core engine for the ADCIRC mesh ecosystem. Sibling projects build on it; CHILmesh depends on none of them.

DomI provides dev-session skills and governance infrastructure for all repos.

• Shipped (v1.0.0): C++ half-edge backend (~24× faster on full init); bit-identical output verified; 36 cross-backend equivalence tests; fort.14 + .2dm I/O; mixed-element support.
• In flight: Pre-built binary wheels (cibuildwheel, manylinux/macOS/Windows) · Rust skeletonization completion (#163) · Full mutation suite (#94)
• Next: conda-forge packaging · mkdocs API site · advancing-front element mutation

Open issues: github.com/domattioli/CHILmesh/issues

• docs/API.md — full API reference
• docs/BENCHMARK.md — benchmark methodology and raw data
• tests/TESTING.md — test guide (pytest markers, local commands)
• examples/ — runnable scripts (quickstart, fort.14 round-trip, smoothing, spatial queries)

CHILmesh originated in MATLAB as the data structure backing a skeletonization-driven indirect tri-to-quad conversion heuristic (Mattioli, OSU MSc thesis, 2017). This Python library is the actively-developed successor.

@software{mattioli_chilmesh,
  author    = {Mattioli, Dominik O. and Kubatko, Ethan J.},
  title     = {{CHILmesh}: a fast 2D mesh library for triangular,
               quadrilateral, and mixed-element grids},
  year      = {2026},
  publisher = {Zenodo},
  version   = {1.0.0},
  doi       = {10.5281/zenodo.20263854},
  url       = {https://github.com/domattioli/CHILmesh}
}

MATLAB source (Mattioli, 2017). Read thesis (PDF)

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

Issues and PRs welcome at github.com/domattioli/CHILmesh. Run pytest -v before opening a PR — see tests/TESTING.md.

Noncommercial / research use only. Licensed under the PolyForm Noncommercial License 1.0.0 with an additional No-AI/ML-training restriction — see LICENSE and .claude/AI-USAGE.md. No commercial use and no use as AI/ML training data without a separate written license. Commercial or AI-training licenses: domburner@duck.com