admesh2D 0.6.0

ADMESH: an advanced, automatic unstructured mesh generator for 2D shallow-water models.

An ADvanced, automatic unstructured MESH generator for 2D shallow-water models
Python API and port of the original MATLAB library

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

Lineage: Two branches of ADMESH descend from the 2012 original by Conroy et al. The original group's current MATLAB line is ADMESH+ v3 (OSU-CHIL/ADMESH; archived at 10.5281/zenodo.10242565), maintained by Younghun Kang with Ethan Kubatko: it adds constraint extraction for coupled 1D–2D hydrodynamic models, a revised medial-axis method, and GUI components (Kang & Kubatko, 2024). This repository is the parallel branch: an independent Python port of the 2012 library, maintained separately. A copy of the ported MATLAB source is vendored at src/matlab/ for provenance.

---

Table of Contents

• Status & roadmap
• Why ADMESH
• Installation
• Quick start
• Pipeline
• Performance
• Citation
• Contributing · Documentation · License

---

Status & Roadmap

Current release: 0.6.0 (July 2026), stable and actively-maintained. The octree adaptive background grid (background="octree") refines the size field on a quadtree to better resolve medial-axis and channel feature widths.

• Now: address open issues.
• Next: enhanced pre- and post-processing for quality improvement; performance optimization; evaluate a C++ or Rust backend; parallelization.
• Future: formal integration within a unified ecosystem including and

---

Why ADMESH

For shallow-water modelers who need ADCIRC-ready meshes with minimal user input:

• Native ADCIRC fort.14 I/O. Bit-faithful read/mesh/write round-trip, including paired-edge boundary records (IBTYPE 3/4/13/24). ADCIRC format only — not gmsh, not generic.
• Element size follows the physics. Size adapts to boundary curvature, channel width, bathymetric gradient, and tidal wavelength through automatic min-stack composition; custom contributions layer on top. No hand-tuned scalar.
• An adaptive background grid for multiscale domains. triangulate(background="octree") refines the size field on a quadtree instead of a uniform grid, concentrating evaluation where the geometry demands it — opt-in; the uniform grid remains the default.
• Pythonic surface, faithful internals. Domain / Mesh / BoundarySegment are frozen, typed dataclasses; the numerics stay inside the locked faithful-port modules.

Not the right tool for 3-D, anisotropic, or non-triangular elements — use for quads, or gmsh otherwise.

Installation

pip install admesh2D            # core
pip install admesh2D[viz]       # adds chilmesh for mesh.plot() / plot_quality()

⚠️ Install admesh2D, not admesh. The distribution name is admesh2D; the import name stays admesh (import admesh). pip install admesh pulls an unrelated C STL-repair library that needs admesh/stl.h at build time and will fail.

Requires Python ≥ 3.10. Core dependencies: NumPy, SciPy, Numba, Shapely. From source:

git clone https://github.com/domattioli/ADMESH.git
cd ADMESH && pip install -e ".[dev]"

Quick start

import admesh
from admesh import domains

# Uniform sizing
mesh = admesh.triangulate(domains.UNIT_DISK, h_max=0.1)
mesh.to_fort14("disk.14")

# Graded sizing: fine features, coarse interior
mesh = admesh.triangulate(domains.NOTCHED_RECTANGLE, h_max=0.2, h_min=0.02)
mesh.to_fort14("notched.14")

mesh is a frozen Mesh dataclass: typed nodes, elements, boundaries (each a BoundarySegment carrying a BoundaryType code), optional bathymetry, and per-element quality. h_min / h_max set the size bounds; pass a size_field callable to grade explicitly. fort.14 boundary labels round-trip through BoundaryType, an IntEnum over ADCIRC IBTYPE codes (OPEN=0, MAINLAND=1, ISLAND=11, MAINLAND_FLUX=20); paired-edge and weir codes (3/4/13/24) preserve as plain int.

See docs/ for fort.14 round-trip, re-meshing, custom size-field, and SDF-domain examples.

Pipeline

triangulate(...) runs the 13-stage ADMESH pipeline; a Numba-JIT solver replaces the original C MEX, so there is no compile step at install.

flowchart LR
    A["SDF / fort.14"] --> B["Domain"]
    B --> C["Size field<br>(curvature + medial axis<br>+ bathymetry + tide)"]
    C --> D["distmesh2d<br>(truss equilibrium)"]
    D --> E["Mesh<br>(fort.14 out)"]

Performance

The Numba-JIT SDF kernel and solve_iter smoother cut end-to-end mesh generation on the Western North Atlantic benchmark from 1257.5 s to 47.2 s — a 26.6× speedup at unchanged quality (mean 0.963), measured at hmin=0.05 / g=0.10 / niter=120.

	v0.2.1	v0.5.0 (Numba)
total	1257.5 s	47.2 s
nodes / elements	49 377 / 93 655	49 377 / 93 642
mean element quality	0.963	0.962

The C++ force kernel and full-stage native rewrite (v1.0.0 / v1.1.0) are in flight; the per-stage breakdown and the version-comparison harness live in benchmarks/. The forward benchmark standard is the ENPAC 2003 tidal database (272,913 nodes), replacing WNAT for large-domain timing.

Reproduce or extend:

python benchmarks/compare_versions.py --hist \
    --mesh tests/fixtures/fort14/adcirc_examples/wnat_test.14 \
    --domain benchmarks/data/wnat_onur_boundary.json \
    --hmin 0.05 --g 0.10 --niter 120

Citation

Algorithm (cite the original paper):

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 (cite the archived release):

Mattioli, D.O., Conroy, C.J., West, D.W., Kubatko, E.J. (2026). ADMESH: An advanced, automatic unstructured mesh generator for 2D shallow-water models (Python port). Zenodo. https://doi.org/10.5281/zenodo.20264101

Upstream MATLAB line (ADMESH+, if you use or compare against it):

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

Kang, Y., Kubatko, E.J., Conroy, C.J. & West, D.W. (2023). Younghun-Kang/ADMESH: v3.0.1. Zenodo. https://doi.org/10.5281/zenodo.10242565

A CITATION.cff feeds GitHub's "Cite this repository" button; version-specific DOIs are on the Zenodo record.

Documentation

API reference lives in the docstrings (triangulate, Domain, Mesh, BoundarySegment, read_fort14 / write_fort14, the 13 stage modules). Design notes, the porting log, and domain-format specs are under docs/ and specs/; project invariants in CONSTITUTION.md.

Contributing

Issues and pull requests are welcome on GitHub.

• Theory (algorithm, size-field formulation, ADCIRC integration): Colton Conroy | Ethan Kubatko
• Upstream MATLAB line (ADMESH+ v3: 1D–2D constraints, medial axis, GUI): Younghun Kang | Ethan Kubatko
• This repository (python port, active maintenance): Dominik Mattioli

License

Apache 2.0 — see LICENSE.