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.0. Next: 0.2.5 (unreleased); 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 walkability and post-process quality tuning.
• Next: pre- and post-processing quality work; performance; evaluate a C++ or Rust backend; wire tri2quad(aggressive=) to CHILmesh merge_elements.
• Future: 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 in 0.2.5 (unreleased). 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

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: kubatko.3@osu.edu

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 domattioli via mango-kooky-okay@duck.com

Back to top