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 ()

• Converts an existing, validated shallow-water triangulation into quadrilaterals by merging adjacent triangle pairs.
• Reuses the input vertices; triangle pairing adds no points. can_remove_edges=False stops boundary-edge collapse.
• Leaves zero interior residual triangles (triangles with no domain-boundary edge), checked by tests/test_no_interior_tris.py.
• Adds points only to clear leftover boundary triangles; this step is on by default and point_insert=False turns it off.
• Returns a quad-pure mesh by default; remove_boundary_tris=False keeps leftover boundary triangles instead.

Attention MATLAB users: This Python library is the actively developed successor to the original MATLAB code, which is no longer maintained and is frozen under archive/matlab.

Table of Contents

1. Status & Roadmap
2. Installation
3. Quick Start
4. Meshes from the Valence registry
5. Limitations
6. Documentation
7. Citation
8. Related Projects
9. Contributing & Contact
10. License

---

1. Status & Roadmap

Current release: 0.2.6 (2026-10-23); see CHANGELOG.

The default method="quadmesh+" runs the thesis per-layer sweep and leaves zero interior residual triangles; CI checks this on the meshes bundled with chilmesh.data. Algorithm and MATLAB parity status: docs/algorithm.md.

• Now: boundary-layer quality, including the ENPAC2003 low-skew tail (#90); right-size the test suite (#109).
• Next: boundary-type-aware layer seeding (#77); a MATLAB parity oracle (#116); wire tri2quad(aggressive=) to CHILmesh merge_elements.
• Later: parallelization (#38); evaluate a C++ or Rust backend; formal integration within a unified ecosystem including and

Headline result: on ENPAC2003 (531,680 triangles), QuADMESH 0.1.0 with chilmesh 1.0.0 produced 274,321 quads with zero interior residual triangles in 773 s, single-threaded. Details: docs/benchmarks.

Back to top

2. Installation

pip install quadmesh                # release from PyPI
pip install -e ".[dev]"             # from a clone, plus pytest
pip install -e ".[plot]"            # plus matplotlib for quality plots

chilmesh is an external dependency and is not vendored. Mesh-dependent tests need a Valence token; see tests/fixtures/README.md.

Back to top

3. Quick Start

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

Useful flags: --polygon domain.poly (domain boundary), --no-post-process, --n-smooth-iter N, --preserve-boundary. Run python -m quadmesh.cli --help for all of them. The MATLAB to Python function map is in MAPPING.md.

Back to top

4. Meshes from the Valence registry

quadmesh --from-registry NAME -o out.14 ships since 0.2.5. Test meshes are available through Valence, a token-gated mesh service.

1. Sign in with GitHub at https://valence-api.iqh766c2.workers.dev .
2. A GitHub account at least 30 days old gets a token at once. The page shows it once; copy it then.
3. A token allows 500 downloads per day (reset at midnight UTC) and expires after one year.

export VALENCE_TOKEN=<your token>; quadmesh --from-registry Block_O.14 -o out.14

Back to top

5. Limitations

• Converts an existing, validated triangulation. It does not generate meshes from scratch.
• Boundary-layer quads have the lowest quality, and some can be concave (#90).
• The default post-process may drop boundary vertices; use preserve_boundary=True to keep them.

Back to top

6. Documentation

• Algorithm and MATLAB mapping
• Python quickstart
• Performance and benchmarks (quadmesh-bench, diagnostics)
• Repository layout, share your mesh

Back to top

7. Citation

Algorithm and 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

A corrected PDF of the thesis, with every cross-reference and citation resolved, is archived at https://doi.org/10.5281/zenodo.23607233 and attached to each GitHub release. The OhioLINK copy prints ?? for figure, chapter and citation references because it was compiled without the bibliography pass.

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.20350483

The DOI resolves to the latest release; version DOIs are on the Zenodo record.

Back to top

8. Related Projects

• ADMESH: Python port of the ADMESH adaptive mesh generator.
• CHILmesh: mesh data structure, smoother, and quality analysis.

Back to top

9. Contributing & Contact

See CONTRIBUTING.md. To share a mesh, open an issue in this repository (https://github.com/domattioli/quadmesh/issues/new).

Dominik Mattioli (repo owner): GitHub | Ethan J. Kubatko: OSU profile

Back to top

10. License

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

Commercial or AI-training licenses: contact the author through GitHub

Back to top