valence-domains 0.4.2

ADCIRC mesh registry - domain management and validation for mesh data

Valence

A curated registry of hydrodynamic domains and meshes — one canonical manifest.toml, with mesh files fetched on demand from a HuggingFace mirror.

Thomas Estep & Dominik Mattioli
^Unaffiliated

---

Table of Contents

• Why Valence
• Installation
• Quickstart
• Examples
• Registry
• Ecosystem
• Status & roadmap
• Citation
• Contact
• License

---

flowchart LR
    A["registry_data/\nmanifest.toml"] --> B["valence_domains/data/\nmanifest.toml\n(bundled in wheel)"]
    A --> C["Parquet sidecar\n(derived at publish)"]
    B --> D["HuggingFace Hub\ndomattioli/Valence"]
    C --> D
    D -->|"Mesh.load()\non demand"| E["chilmesh.Mesh"]

Why Valence

Hydrodynamic mesh data is scattered across papers, lab drives, and agency portals, and rarely reproducible. Valence consolidates it into one catalog of 13 Domains and 40 Meshes (~59 MB), addressable by composite ID (WNAT/hagen@v1):

• One canonical manifest.toml is the single source of truth for every mesh's metadata — provenance, element type, lineage. The Parquet sidecar is derived from it at publish time, never authoritative.
• Mesh files load on demand. Mesh.load() pulls a .14/.2dm from the HuggingFace mirror and caches it; the base wheel ships no mesh bytes (~50 KB install).
• Contribution is a validated pull request. The PR validator runs on every push; provenance is mandatory, so a generated stand-in cannot masquerade as a published mesh.
• Code and data release on separate tracks. Code/API/schema changes tag vX.Y.Z → PyPI + HF; mesh add/edit publishes to HF only (data-YYYY-MM-DD-<sha7>), leaving the PyPI version untouched.

Browse the registry at domattioli.github.io/Valence — interactive map, search, preview, download, contribute.

Surface	Contents
domattioli.github.io/Valence	Website — browse / preview / download / contribute
pypi.org/project/valence-domains	Python package
huggingface.co/datasets/domattioli/Valence	Mesh files + Parquet sidecar + dataset card

This repository holds the data, schema, publisher pipeline, and CI for contributors and maintainers. End users do not clone it — pip install valence-domains[hf] is enough.

Installation

pip install valence-domains          # bundled manifest only (~50 KB, no mesh downloads)
pip install valence-domains[hf]      # + Mesh.load() — fetches mesh files from the HF mirror
pip install valence-domains[gen]     # + the synthetic-mesh generator (numpy + scipy)

The query API (find_domains, find_meshes, get_mesh, test_meshes, Mesh.load) is documented on the HF dataset card. For pytest fixtures, from valence_domains import test_meshes returns every registry mesh flagged for testing.

Quickstart

The generator writes deterministic fort.14 meshes for tests, docs, and comparison fixtures:

valence-domains generate --output mesh.14 --seed 42 --node-count 500
valence-domains generate --output tri.14  --element-type triangle --seed 1
valence-domains generate --output quad.14 --element-type quad     --seed 1

Identical --seed + --node-count + --element-type produce byte-identical output. Requires the [gen] extra.

Examples

Query the registry and load a mesh on demand (requires the [hf] extra):

from valence_domains import find_domains, find_meshes, get_mesh, test_meshes

find_domains()                      # every domain in the manifest
find_meshes(domain="WNAT")          # meshes within a domain

mesh = get_mesh("WNAT/hagen@v1")    # fetches from the HF mirror, cached
nodes, elements = mesh.load()       # fort.14 contents

for m in test_meshes():             # meshes flagged as test fixtures
    ...

Full API reference: the HuggingFace dataset card.

Registry

src/valence_domains/      Python package — schema, manifest loader, query API,
                          CLI, HF publisher, dataset-card template
src/valence_domains/data/ Bundled manifest.toml shipped in the wheel
registry_data/            Source-of-truth manifest + mesh files (.14, .2dm);
                          excluded from wheel/sdist, mirrored to HF
specs/                    Spec-driven design docs (one folder per feature)
scripts/                  One-shot data tooling (mesh import, bbox extractor)
tests/                    pytest suite (mocked huggingface_hub)
.github/workflows/        release.yml (tag → PyPI + HF), validate-pr.yml (CI)

Ecosystem

Repo	Role
CHILmesh	Core mesh engine; Mesh.from_admesh_domain() reads from this registry
ADMESH	Triangle mesh generator this registry complements; WNAT_Hagen.14 is its reference domain
QuADMESH	Quad mesh generator; uses registry domains as test inputs
MADMESHing	Benchmark harness; pulls Block-O from this registry

Status & roadmap

• Shipped — valence-domains 0.4.1 on PyPI (renamed from admesh-domains, which remains a stub that redirects to it). Registry holds 13 Domains + 40 Meshes (~59 MB), mirrored to domattioli/Valence on HuggingFace.
• Next — content-UID identity for deduplication, domain lineage graph, expanded test-suite coverage.

See CHANGELOG.md for the full release history.

Citation

Mattioli, D. & Estep, T. (2026). Valence: Curated registry of hydrodynamic domains and meshes. Zenodo. https://doi.org/10.5281/zenodo.20519657

Contact

• Thomas Estep — github.com/thomas-estep
• Dominik Mattioli — github.com/domattioli

License

Noncommercial / research use only. 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; for either, contact Dominik Mattioli at [e-mail].