valence-domains 0.4.1

ADCIRC mesh registry - domain management and validation for mesh data

Valence

Curated registry of hydrodyanmic domain and meshes — a canonical `manifest.toml` with on-demand mesh fetch from the HuggingFace mirror.

Thomas Estep^1† & Dominik Mattioli^1†, ^†Corresponding author | ¹Unaffiliated | ²Ohio State University (CHIL)

---

Table of Contents

• Why Valence
• Install
• Quickstart
• 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(auto-generated)"]
    B --> D["HuggingFace Hub\ndomattioli/Valence"]
    C --> D
    D -->|"Mesh.load()\non demand"| E["chilmesh.Mesh"]

Why Valence

Hydrodynamic mesh data is scattered and hard to reproduce. Valence provides a single curated catalog with:

• Canonical manifest.toml — one source of truth for mesh metadata (provenance, element type, lineage).
• On-demand fetch — Mesh.load() pulls from the HuggingFace mirror; no bulk download required.
• PR-based contribution — add a new domain mesh through a validated pull request; validator runs on every push.
• Reproducible data releases — code changes → PyPI + HF tagged vX.Y.Z; data updates → HF tagged data-YYYY-MM-DD-<sha7>, PyPI untouched.

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

Where to go	What you'll find
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 + auto-generated dataset card

This repo is for contributors and maintainers — data, schema, publisher pipeline, and CI live here. End users normally don't need to clone; pip install valence-domains[hf] is enough.

Install

# Read bundled manifest only (no mesh downloads, ~50 KB install)
pip install valence-domains

# Add Mesh.load() — fetches mesh files from HF mirror on demand
pip install valence-domains[hf]

# Add synthetic-mesh generator (numpy + scipy)
pip install valence-domains[gen]

User-facing API (find_domains, find_meshes, get_mesh, test_meshes, Mesh.load) documented on the HF dataset card. For pytest fixtures, use from valence_domains import test_meshes — returns all registry meshes marked for testing.

Quickstart

Deterministic random fort.14 generator for tests, documentation, and mesh-comparison fixtures:

# Write a single deterministic fort.14
valence-domains generate --output mesh.14 --seed 42 --node-count 500

# Triangle / quad / mixed elements
valence-domains generate --output tri.14  --element-type triangle --seed 1
valence-domains generate --output quad.14 --element-type quad     --seed 1

Same --seed + --node-count + --element-type → byte-identical output. Requires the [gen] extra (numpy + scipy).

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

# Discover what's registered
find_domains()                      # all domains in the manifest
find_meshes(domain="WNAT")          # meshes within a domain

# Fetch a specific mesh (downloads from the HuggingFace mirror, cached)
mesh = get_mesh("WNAT/hagen@v1")
nodes, elements = mesh.load()       # fort.14 contents

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

See the HuggingFace dataset card for the full API reference.

Registry

Repo layout

valence/                 Python package (schema, manifest loader, query API,
                         CLI, HF publisher, dataset-card template)
valence/data/            Bundled manifest.toml shipped in 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	Mesh generator this registry complements; WNAT_Hagen.14 is the ADMESH reference domain
QuADMesh	Quad mesh generator; uses registry domains as test inputs
MADMESHing	Benchmark harness; pulls Block-O from this registry

HuggingFace slug: domattioli/Valence.

Status & Roadmap

Coming soon

See CHANGELOG.md for full release history.

Citation

This software (cite the archived release):

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

Contact

Thomas Estep - (repo co owner)

Dominik Mattioli - (repo co owner)

License

Noncommercial / research use only. Licensed under the 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. Commercial or AI-training licenses: contact domattioli via [e-mail]