quadmesh 0.2.0

QuADMESH+: Quadrangular ADvanced Mesh generator. Python port of MATLAB QuADMESH library.

A Quadrangular ADvanced, automatic unstructured MESH generator for 2D shallow-water models.
Python API and port of the MATLAB library and 'QuADMESH+'

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

Attention MATLAB users: This Python library is the actively-developed successor to the original MATLAB codebase. The original code (no longer maintained) is frozen under src/matlab/quadmesh.

---

Table of Contents

• Status & Roadmap
• Installation
• Repository Layout
• Quick Start
• Performance
• Citation
• Related Projects
• Contact
• License

---

Status & Roadmap

Current status (June 2026): Work-in-Progress, but mostly functional. The QuADMESH+ layer-ordered tri-to-quad conversion is implemented and is the default method="quadmesh+". The interior-saturating per-layer sweep (thesis Ch 4.1 IE-before-OE, Ch 4.2 fold-seam forbiddance) leaves zero interior residual triangles by construction — the faithfulness invariant. Post-process mean element quality needs improvement (degen. elements on the boundary).

• Now: boundary-layer walkability and post-process quality tuning. (The isolated-triangle edge-swap fixup is confirmed a no-op on all offline-testable meshes — disposition pending deprecation review, not active work.)
• Next: enhanced pre- and post-processing for quality improvement; performance optimization; evaluate a C++ or Rust backend; wire tri2quad(aggressive=) to CHILmesh merge_elements.
• Future: formal integration within a unified ecosystem including and

---

Installation

Alpha build

pip install quadmesh

# From the repo root (src-layout package)
pip install -e .            # Basic install
pip install -e ".[dev]"     # + pytest for the test suite
pip install -e ".[plot]"    # + matplotlib for quality plots

Test the installation:

pytest -q                          # 169 tests (101 run offline; mesh-dependent
                                   # tests need a Valence PAT — see tests/fixtures/README.md)
python -m quadmesh.cli in.14 -o out.14

---

Repository Layout

src/quadmesh/       Python package (the maintained implementation)
tests/              pytest suite; tests/fixtures/meshes/ holds .14 test meshes
docs/               MAPPING.md (MATLAB → Python), session notes
specs/              speckit specs/plans/tasks
videos/             demo assets (quadmesh_logo.gif, render scripts)
src/matlab/         frozen legacy MATLAB reference (read-only, not installable)
archive/            in-repo holding pen: upstream dups, .mat binaries, old results

Note on CHILmesh: Functionality is not vendored — it is an external dependency (chilmesh>=1.2.1). The old MATLAB @CHILmesh class lives under archive/ for historical reference only; see CHILmesh.

---

Quick Start

Convert a triangular fort.14 mesh to quad-dominant with the default QuADMESH+ method:

python -m quadmesh.cli input.14 -o output.14

Useful flags: --polygon domain.poly (supply the domain boundary), --no-post-process (skip the quality smoother), --n-smooth-iter N (smoother iterations). Run python -m quadmesh.cli --help for the full list.

See MAPPING.md for the MATLAB → Python function correspondence and current port status.

---

Performance

On the largest mesh in the Valence registry — ENPAC2003, the Eastern North Pacific tidal grid of 531,680 triangles across 272,913 nodes — QuADMESH+ returns a fully quadrilateral mesh of 274,321 quadrilaterals with zero interior residual triangles (the faithfulness invariant) in 773 s (12.9 min), single-threaded, on the chilmesh 1.0.0 backend.

Phase timing

Single run, single thread, measured at QuADMESH 0.1.0 with the chilmesh 1.0.0 backend. The post-process stage — doublet collapse, boundary cleanup, and the FEM smoother — dominates the wall-clock budget; the layer-ordered tri-to-quad sweep is the second cost.

Phase	Time (s)	Share
Load + half-edge initialization	33.9	4.4%
create_quad_domain	15.0	1.9%
tri2quad_routine (layer-ordered sweep)	186.8	24.2%
post_process_routine (collapse + cleanup + FEM smooth)	537.6	69.5%
Total	773.3	100%

Element quality

Skew quality on the unit interval (1 = an ideal square; the chilmesh element_quality(metric="skew") metric), reported before (input triangles) and after (output quadrilaterals).

Metric	Input triangles	Output quads
Mean	0.875	0.722
Median	0.897	0.783
Minimum	0.150	0.000
Std. dev.	0.081	0.241
Fraction below 0.30	0.0%	7.6%

Recombining two triangles into one quadrilateral trades a measurable amount of per-element quality (mean skew 0.875 → 0.722) for the element-count halving and the all-quad topology. The sub-0.30 tail is 7.6% of elements and is near-exclusively a boundary-layer artifact: skeletonization layer 0 — the boundary band — carries 20,888 of the 20,918 low-quality quads at a 20.5% bad-rate and a mean skew of 0.552, while every interior layer (1 and inward) holds at mean skew ≥ 0.80, rising monotonically to 0.967 at the innermost layer. Of the low-quality quads, 93.0% touch the domain boundary along two or more edges — the near-degenerate boundary-following quads that the FEM smoother cannot relax because their nodes are pinned to the boundary. The Gulf of California subset below shows the regular interior quads against this thin boundary band:

QuADMESH+ output over the Gulf of California (subset of the ENPAC2003 domain).

The boundary-layer quality limitation is tracked in #90; both measurements above are reproducible from the repository:

# per-phase timing + quality histogram for any fort.14 mesh
python scripts/bench_quadmesh_plus.py --mesh path/to/mesh.14

# classify low-quality quads by mesh layer and boundary contact
python scripts/diagnose_bad_quads.py --mesh path/to/mesh.14 --tag mymesh

---

Citation

Algorithm & theory (cite the original thesis):

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

This software (cite the Zenodo release):

Mattioli, DO, Kubatko, EJ (2026). QuADMESH: A Quadrangular ADvanced, automatic unstructured MESH generator for 2D hydrodynamic domains. Zenodo. https://doi.org/10.5281/zenodo.20351165

The DOI 10.5281/zenodo.20351165 resolves to the latest release; version-specific DOIs are listed on the Zenodo record.

---

Related Projects

• ADMESH — Python port of the ADMESH adaptive mesh generator with pythonic API.
• CHILmesh — Mesh data structure, smoother, and quality analysis for triangular and quadrilateral meshes.

---

Contact

Dominik Mattioli (repo owner) — GitHub
Ethan J. Kubatko — [e-mail]

---

License

Noncommercial / research use only. Licensed under the PolyForm Noncommercial License 1.0.0 with an additional No-AI/ML-training restriction — see LICENSE and AI-USAGE.md.

No commercial use and no use as AI/ML training data without a separate written license. Commercial or AI-training licenses: contact domattioli via [e-mail]

---

_{Regenerate logo GIF: python videos/scripts/render_logo_gif.py (matplotlib only, no ffmpeg).}