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
• Quick start
• Examples
• Demos
• 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 registry of 14 Domains and 46 Meshes (~112 MB) (27 of the Meshes sit in 5 Collections, which are not Domains), 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.

These are the public release surfaces:

Surface	Contents
domattioli.github.io/Valence	Website — browse / preview / download / contribute (planned)
pypi.org/project/valence-domains	Python package (published; 0.4.3 is the current release)
huggingface.co/datasets/domattioli/Valence	Mesh files + Parquet sidecar + dataset card (not yet published)

This repository holds the data, schema, publisher pipeline, and CI for contributors and maintainers. End users do not need to 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.

Quick start

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")    # registry metadata (no download yet)
fort14_path = mesh.load()           # downloads from the HF mirror, cached → local Path

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

Full API reference: the HuggingFace dataset card.

Demos

Start here — the canonical offline walkthrough:

make venv && make demo     # offline, deterministic, ~1–2 min; no key/credential/network

make demo runs examples/build_proposal_notebook.py --check: the intent-guided region-proposal notebook executed end to end offline — compile structured constraints (supported / advisory / unsupported diagnostics) → rank deterministic proposals from precomputed synthetic selection artifacts → cross the single human-approval boundary to an approved region. It is the first thing to send a new evaluator, collaborator, user/funder, or developer.

Valence's region-proposal → change-controlled review subsystem is also demonstrated through the hosted web lifecycle. Full detail (audience, runtime, internet, optional deps, exact command, what each proves vs. does not) is in docs/DEMO-MATRIX.md. The public product imports precomputed SegmentAnyMesh selection artifacts and ranks them by your constraints (the always-available path). In-product candidate generation from constraints is wired but runs only with the proprietary, owner-only SegmentAnyMesh engine (not publicly installable); without it the produce path fails closed with an actionable error, never a fixture. It is advisory planning, not a claim of scientific necessity, optimality, or simulation accuracy; approval is a human gate (see docs/current-capability-model.md).

Want to…	Run	Needs
Get started (canonical, offline)	make demo (= build_proposal_notebook.py --check)	.venv only
See the real product (constraints + selection artifacts → ranked proposals → approve → review)	Web lifecycle at /projects/[id]/…	backend + npm run dev
Reproduce the whole chain offline / in CI	Portable notebook: .venv/bin/python examples/build_proposal_notebook.py --check	.venv only

Walkthroughs (CLI + timed demo scripts): docs/DEMO-GUIDE.md. No demo needs an LLM or network at run time.

Registry

packages/valence_domains/      Python package — schema, manifest loader, query API,
                               CLI, HF publisher, dataset-card template
packages/valence_domains/data/ Bundled manifest.toml shipped in the wheel
apps/backend/             FastAPI contribution backend (Vercel)
apps/frontend/            Next.js site (Vercel)
registry_data/            Source-of-truth manifest + mesh files (.14, .2dm);
                          excluded from wheel/sdist, mirrored to HF
DomI/specs/consumers/Valence/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

• Status — package version 0.4.3, published on PyPI as valence-domains. Registry holds 14 Domains + 46 Meshes (~112 MB), 27 of them in 5 Collections. Code and data release on separate tracks (PyPI + HF for code/schema; HF only for data) — see CHANGELOG.md for the per-version history.
• 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. (DOI pending publication.)

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. No commercial use and no use as AI/ML training data without a separate written license; for either, contact Dominik Mattioli at https://github.com/domattioli.