An ADvanced, automatic unstructured MESH generator for 2D shallow-water models
Automatic unstructured mesh generation for shallow-water models, in Python and MATLAB

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

Background: Two branches of ADMESH descend from the 2012 original by Conroy et al.. The original group's MATLAB line is ADMESH+ v3 (OSU-CHIL/ADMESH; 10.5281/zenodo.10009711), maintained by Younghun Kang and Ethan Kubatko (Kang & Kubatko, 2024). This repository is the parallel branch: the 2012 library in Python, with the MATLAB source alongside at src/matlab/.

Table of Contents

1. Status & Roadmap
2. Overview
3. Installation
4. Quick start
5. Meshes from the Valence registry
6. Pipeline
7. Performance
8. Limitations
9. Citation
10. Documentation, Contributing, License

1. Status & Roadmap

Current release: 1.1.0 (2026-11-11); see CHANGELOG. The public API (admesh.__all__, listed in docs/api/index.md) is fixed for 1.x. The admesh.<stage> compatibility modules stay through 1.x and are removed no earlier than 2.0.

• Now: 1D–2D constraint extraction (#186).
• Next: single-mesh parallel speed-up (#216, #218).
• Later: 3D ADMESH (#220); integration with QuADMESH (quads) and CHILmesh (mesh data structure and smoothing).

2. Overview

triangulate() takes a domain (a Domain, TOML or JSON polygon file, fort.14, or registry filename) and two edge-length bounds, and returns a validated mesh. Without a size field, the size is uniform at h_max. Physics-based sizing and background="octree" are opt-in. The 13 numerical stages exist in both Python and MATLAB; a Numba solver replaces the original C MEX.

3. Installation

pip install admesh2D                 # core: NumPy, SciPy, Numba, Shapely
pip install "admesh2D[viz]"          # + chilmesh for mesh.plot()

The PyPI distribution is admesh2D; the import name is admesh. (pip install admesh installs an unrelated STL library.) Requires Python 3.11 or newer. From source: git clone https://github.com/domattioli/ADMESH.git && cd ADMESH && pip install -e ".[dev]".

4. Quick start

import admesh
from admesh import domains

# Built-in domain, uniform sizing at h_max.
mesh = admesh.triangulate(domains.NOTCHED_RECTANGLE, h_max=0.2, h_min=0.02)
mesh.to_fort14("notched.14")
# Re-mesh an existing ADCIRC grid at a new resolution.
old = admesh.read_fort14("legacy.14")
mesh = admesh.triangulate(admesh.Domain.from_mesh(old), h_min=50.0, h_max=2000.0)

mesh is a frozen Mesh dataclass with nodes, elements, boundaries, optional bathymetry, and per-element quality. Built-in domains: UNIT_SQUARE, UNIT_DISK, L_SHAPE, ANNULUS, NOTCHED_RECTANGLE. The full call list is in docs/api/index.md.

5. Meshes from the Valence registry

The HTTP registry client ships in admesh2D 1.0.5 and later. Meshes come through Valence, a token-gated mesh service.

Sign in with GitHub at https://valence-api.iqh766c2.workers.dev . A GitHub account at least 30 days old gets a token at once, shown once. Each token allows 500 downloads per token per day (reset at midnight UTC) and expires after one year.

export VALENCE_TOKEN=<your token>

import admesh
domain = admesh.load_domain_from_registry("rectangular_mesh_triangle1.14")
mesh = admesh.triangulate(domain)

Each download is checked against its SHA-256 hash. See the Registry API contract.

6. Pipeline

triangulate() composes the stage modules in admesh/_stages/, which match the MATLAB library one to one and are locked.

Domain, then background grid (uniform or octree), then size field (curvature, medial axis, bathymetry, tide; min-stacked), then distmesh2d truss relaxation (Numba), then a validated Mesh (fort.14 or .msh).

7. Performance

Numba kernels cut end-to-end generation on the Western North Atlantic benchmark from 1257.5 s (v0.2.1) to 47.2 s (v0.5.0), a 26.6x speedup. triangulate_batch runs 5.09x faster on 8 workers than a serial loop. Tables, method and reproduction commands: docs/BENCHMARK_DELIVERABLE.md.

8. Limitations

• Triangles only, in 2-D. For quads use QuADMESH; for 3-D or anisotropy use Gmsh.
• The 2012 algorithm as published. The vector-distance-transform medial axis of Kang & Kubatko (2024) is the opt-in medial_method="vdt"; the 1D–2D constraint extraction is not implemented.
• Default sizing is uniform. The physics-based size contributions are not wired in by default (issue #65).
• Generated meshes carry no bathymetry, and fort.14 IBTYPE 3/4/13/24 paired-node and weir columns are not preserved.
• One process per mesh, CPU only. The distmesh relaxation dominates wall-clock time on large domains.
• Browser app: admesh.domattioli.com runs ADMESH in the page through Pyodide, without Numba.

9. Citation

• Algorithm: Conroy, C.J., Kubatko, E.J. & West, D.W. (2012). ADMESH: an advanced, automatic unstructured mesh generator for shallow water models. Ocean Dynamics 62, 1503–1517. https://doi.org/10.1007/s10236-012-0574-0
• This software: Mattioli, D.O., Conroy, C.J., West, D.W., Kubatko, E.J. (2026). ADMESH: automatic unstructured triangular mesh generator for 2D shallow-water models (Python). Zenodo. https://doi.org/10.5281/zenodo.20264085
• Upstream MATLAB line: Kang, Y. & Kubatko, E.J. (2024). An automatic mesh generator for coupled 1D–2D hydrodynamic models. Geoscientific Model Development 17, 1603–1625. https://doi.org/10.5194/gmd-17-1603-2024
• A CITATION.cff feeds GitHub's "Cite this repository" button. Version-specific DOIs are on the Zenodo record.

10. Documentation, Contributing, License

• Docs: docs/quickstart.md, docs/DOMAIN_IO.md, docs/api/, docs/PORTING_NOTES.md, docs/adr/, docs/gallery/.
• Contributing: issues and pull requests on GitHub; see CONTRIBUTING.md. To share a fort.14 mesh, open an issue in this repository (details: docs/share-your-mesh.md).
• Theory: Colton Conroy | Ethan Kubatko. Upstream MATLAB line: Younghun Kang. This repository: Dominik Mattioli.

Acknowledgement. Code added after the original MATLAB port was written using AI coding tools built on Anthropic and OpenAI models. The 13 ported stages are checked against the MATLAB reference tests.

License. Apache-2.0; a port of the MIT-licensed ADMESH (see NOTICE). A non-binding request about AI training is in AI-TRAINING.md.