hhemt 0.1.0__tar.gz

hhemt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,153 @@
+# Contributing
+
+## Licensing of contributions
+
+This project is currently released under the
+[PolyForm Noncommercial License 1.0.0](LICENSE).
+
+By submitting a contribution (a pull request, patch, or any other work)
+to this project, you agree that:
+
+1. **Inbound = outbound.** Your contribution is provided under the same
+   license as the project (PolyForm Noncommercial License 1.0.0), and
+   you have the right to submit it under that license.
+
+2. **Forward relicensing.** You grant the maintainer permission to
+   license your contribution under any future license the project
+   adopts, including a permissive OSI-approved open-source license
+   (for example, Apache License 2.0). This lets the project relicense
+   in the future without requiring sign-off from every past contributor.
+
+If you cannot agree to these terms for a particular contribution, please
+open an issue to discuss before submitting.
+
+## Development setup
+
+1. Fork and clone the repository
+2. Create a conda environment or virtual environment
+3. Install in development mode: `pip install -e ".[docs]"`
+4. Install pre-commit hooks: `pre-commit install`
+
+## Workflow
+
+- Create a feature branch from `develop`
+- Make changes with tests
+- Run `ruff check .` and `ruff format .`
+- Run `pytest`
+- Submit a pull request
+
+## Documentation
+
+Build docs locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Branching and releases
+
+`develop` is the default branch; all work branches from and merges back into `develop`. `main` is release-only and advances only via a validated `develop` → `main` release pull request (all tests green, docs complete), tagged `vX.Y.Z`. See [Branching and release model](docs/explanation/branching-and-release-model.md) for the full model, the release procedure, and the Read-the-Docs default-version runbook.
+
+---
+
+## Development Principles
+
+### Raise questions rather than make assumptions
+When you encounter uncertainty or discrepancies — especially when implementing a pre-written plan that may have stale components — err on the side of caution and ask the developer how to proceed.
+
+### Plan, then implement
+Follow a plan-then-implement strategy. If implementing a plan uncovers a need to change it or its success criteria — including deviations from the planned approach, scope changes, or new risks — raise the discrepancy before continuing rather than adapting silently.
+
+### Let's do things right, even if it takes more effort
+- Always be on the lookout for better ways of achieving development goals and raise these ideas
+- Raise concerns when you suspect the developer is making design decisions that diverge from best practices
+- Look for opportunities to make code more efficient (vectorize operations, avoid loops with pandas, etc.)
+
+### Backward compatibility is NOT a priority
+
+**Rationale**: Single developer codebase. Clean code matters more than preserved APIs. Git history is the safety net.
+
+When refactoring:
+- ❌ Don't add deprecation warnings
+- ❌ Don't keep old APIs "for compatibility"
+- ❌ Don't create compatibility shims or aliases
+- ✅ Do update all usage sites immediately
+- ✅ Do delete obsolete code completely
+
+### Most function arguments should not have defaults
+
+Default function arguments can lead to difficult-to-debug unexpected behavior. Avoid default values unless a default is almost always the correct choice (e.g., `verbose=True`). This is especially true for configuration fields that users populate — the user should make an intentional choice about every input.
+
+### Avoid aliases
+
+Do not create aliases for functions, classes, or variables. An alias is a second name for the same thing — it creates confusion about which name is authoritative and is a form of backward-compatibility shim. If something needs renaming, rename it and update all call sites.
+
+### No cruft/all variables, imports, and function arguments must be used
+
+Unused elements are a signal that implementation may be incomplete. Treat them as an investigation trigger, not just lint to suppress.
+
+If you come across an unused variable, import, or function argument, investigate before removing:
+1. Check whether the surrounding implementation is incomplete
+2. Find planning documents that touched that function and determine whether implementation is planned
+3. If still uncertain, raise the concern with the developer with hypotheses about why it exists
+4. The only exception: elements included for a currently-planned implementation, marked with a comment referencing the planning document
+
+Report your observations, hypotheses, and recommendations to the developer.
+
+After investigation and with approval from the developer, remove unused code, dead branches, commented-out blocks, and stale imports.
+
+### Functions have docstrings, type hints, and type checking
+
+Apply this standard to code you write or modify. For existing code in touched scripts, apply organically — accumulate adherence naturally as scripts are touched rather than doing a global retrofit pass.
+
+### Fail-fast
+
+Critical paths must raise exceptions; never silently return `False` or `None` on failure.
+
+### Preserve context in exceptions
+
+Exceptions should include file paths, return codes, and log locations for actionable debugging.
+
+### Prefer log-based completion checks over file existence checks
+
+A file may exist but be corrupt, incomplete, or from a previous failed run. File existence checks can mask errors when log checks are available.
+
+- **Exception**: File existence is appropriate for verifying *input* files before reading them.
+
+### Keep system-agnostic software
+
+System-specific information belongs in user-defined configuration files. Avoid hardcoded paths or machine-specific constants in core code.
+
+### Track project-agnostic utility candidates
+
+When writing utility functions that could plausibly belong in a shared library (e.g., general-purpose file I/O helpers, generic array operations), note them in a dedicated tracking document. Do not extract them immediately — track them so they can be evaluated together.
+
+---
+
+## AI Workflow
+
+This project uses Claude Code with structured workflow skills. When working with AI assistance:
+
+- `CONTRIBUTING.md` — development principles and working norms (this file)
+- `CLAUDE.md` — AI-specific working norms and project context (auto-loaded by Claude Code)
+- `architecture.md` — project structure and key modules
+
+Workflow skills (available globally, invoke by name):
+- `/implementation-plan` — design a complete plan before coding
+- `/proceed-with-implementation` — preflight check before implementing a plan
+- `/qaqc-and-commit` — post-implementation QA review and commit
+
+---
+
+## Docstring standard
+
+Public methods and modules use **NumPy-style docstrings** (the `numpydoc`
+`Parameters`/`Returns`/`Raises` section convention). The documentation site
+(`mkdocs build`) renders these via the `mkdocstrings` Python handler configured
+with `docstring_style: numpy`, so a docstring that follows this convention is
+rendered correctly in the API reference with no further annotation.
+
+Backfilling docstrings onto currently-undocumented public methods is tracked
+separately (it depends on the public-API surface designation); contributors
+adding NEW public methods should include a NumPy-style docstring at authoring time.

hhemt-0.1.0/HISTORY.md

@@ -0,0 +1,17 @@
+# Release history
+
+## v0.1.0 (2026-XX-XX)
+
+First public release of the H&H Ensemble Modeling Toolkit (hhemt). Coupled
+TRITON-SWMM flood-ensemble orchestration across local + HPC (NVIDIA/AMD), full
+preprocessing→compile→run→process→consolidate→report lifecycle, interactive
+analysis report, and a portable render-bundle. Docs at
+https://hhemt.readthedocs.io. Cite via the Zenodo DOI (see README).
+
+**Installation — pip installs the toolkit, conda runs SWMM.** `pip install hhemt`
+installs the Python package and its pure-Python dependencies, but a plain pip
+environment **cannot execute SWMM**: the pinned SWMM runoff engine is provisioned
+only through the conda environment (`environment.yaml`). This is a deliberate
+fail-closed dependency contract — a bare pip install raises a clear error at SWMM
+execution time rather than silently running against an untested engine build.
+Conda is therefore the supported path for running simulations.

hhemt-0.1.0/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

hhemt-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CONTRIBUTING.md
+include HISTORY.md
+include LICENSE
+include README.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.md Makefile *.jpg *.png *.gif

hhemt-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: hhemt
+Version: 0.1.0
+Summary: Tools for running and processing TRITON-SWMM models.
+Author-email: Daniel Lassiter <daniel.lassiter@outlook.com>
+Maintainer-email: Daniel Lassiter <daniel.lassiter@outlook.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+Project-URL: bugs, https://github.com/lassiterdc/hhemt/issues
+Project-URL: changelog, https://github.com/lassiterdc/hhemt/blob/main/changelog.md
+Project-URL: homepage, https://github.com/lassiterdc/hhemt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: filelock
+Requires-Dist: pydantic==2.7.*
+Requires-Dist: pyyaml
+Requires-Dist: zarr
+Requires-Dist: netcdf4
+Requires-Dist: h5netcdf
+Requires-Dist: h5py
+Requires-Dist: scipy
+Requires-Dist: dask
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: sparse
+Requires-Dist: pint
+Requires-Dist: bagit
+Requires-Dist: openpyxl
+Requires-Dist: rioxarray
+Requires-Dist: geopandas
+Requires-Dist: pyproj
+Requires-Dist: shapely
+Requires-Dist: hsclient
+Requires-Dist: requests>=2.25
+Requires-Dist: pyswmm<3,>=2
+Requires-Dist: swmm-toolkit<0.17,>=0.15
+Requires-Dist: swmmio<0.8.3
+Requires-Dist: tabulate
+Requires-Dist: notebook
+Requires-Dist: jupyter_server
+Requires-Dist: ipywidgets
+Requires-Dist: globus-sdk>=3.0
+Requires-Dist: plotly==5.24.1
+Requires-Dist: kaleido!=0.2.1.post1,<1.0,>=0.2.1
+Requires-Dist: datashader>=0.16
+Requires-Dist: jinja2>=3.1
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: snakemake==9.15.0
+Requires-Dist: rocrate==0.15.0
+Provides-Extra: test
+Requires-Dist: ruff==0.15.10; extra == "test"
+Requires-Dist: ty; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-xdist>=3.0; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Provides-Extra: viz-export
+Provides-Extra: hpc
+Requires-Dist: snakemake-executor-plugin-slurm<3,>=2.0; extra == "hpc"
+Requires-Dist: snakemake-executor-plugin-slurm-jobstep<1,>=0.3; extra == "hpc"
+Requires-Dist: snakemake-storage-plugin-fs==1.1.3; extra == "hpc"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-htmlproofer-plugin; extra == "docs"
+Dynamic: license-file
+
+# H&H Ensemble Modeling Toolkit
+
+![PyPI version](https://img.shields.io/pypi/v/hhemt.svg)
+[![Documentation Status](https://readthedocs.org/projects/hhemt/badge/?version=latest)](https://hhemt.readthedocs.io/en/latest/?version=latest)
+
+Tools for running and processing TRITON-SWMM models.
+
+* PyPI package: https://pypi.org/project/hhemt/
+* License: [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+* Documentation: https://hhemt.readthedocs.io.
+
+## Installation
+
+The full toolkit — including SWMM hydrology execution — is validated only against
+the conda environment shipped in this repo. This is the supported install:
+
+```bash
+conda env create -n hhemt --file environment.yaml
+conda activate hhemt
+pip install --no-deps "swmmio==0.8.5"
+pip install -e . --no-deps
+```
+
+Both `--no-deps` steps are required. The validated SWMM engine (`swmm-toolkit`
+0.15.x + `pyswmm` 2.0.1) is only available from conda-forge and cannot be
+expressed as pip metadata, so a plain `pip install hhemt` installs an unvalidated
+SWMM stack: everything except SWMM *execution* works, and SWMM execution fails
+closed with an actionable error pointing here. See
+[`docs/how-to/installation.md`](docs/how-to/installation.md) for details.
+
+## Usage
+
+```bash
+hhemt --help          # CLI entry point
+```
+
+See the [documentation](https://hhemt.readthedocs.io) for the end-to-end
+analysis workflow.
+
+## How to cite
+
+If you use this software, please cite it. Citation metadata is maintained in [`CITATION.cff`](CITATION.cff) (GitHub's "Cite this repository" resolves it). Once the first release is published, cite the specific version via its Zenodo DOI:
+
+<!-- The Zenodo concept-DOI badge is added when the first release DOI is minted (first-public-release):
+[![DOI](https://zenodo.org/badge/DOI/PLACEHOLDER.svg)](https://doi.org/PLACEHOLDER) -->
+
+## Credits
+
+This package was created with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) project template.

hhemt-0.1.0/README.md

@@ -0,0 +1,49 @@
+# H&H Ensemble Modeling Toolkit
+
+![PyPI version](https://img.shields.io/pypi/v/hhemt.svg)
+[![Documentation Status](https://readthedocs.org/projects/hhemt/badge/?version=latest)](https://hhemt.readthedocs.io/en/latest/?version=latest)
+
+Tools for running and processing TRITON-SWMM models.
+
+* PyPI package: https://pypi.org/project/hhemt/
+* License: [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+* Documentation: https://hhemt.readthedocs.io.
+
+## Installation
+
+The full toolkit — including SWMM hydrology execution — is validated only against
+the conda environment shipped in this repo. This is the supported install:
+
+```bash
+conda env create -n hhemt --file environment.yaml
+conda activate hhemt
+pip install --no-deps "swmmio==0.8.5"
+pip install -e . --no-deps
+```
+
+Both `--no-deps` steps are required. The validated SWMM engine (`swmm-toolkit`
+0.15.x + `pyswmm` 2.0.1) is only available from conda-forge and cannot be
+expressed as pip metadata, so a plain `pip install hhemt` installs an unvalidated
+SWMM stack: everything except SWMM *execution* works, and SWMM execution fails
+closed with an actionable error pointing here. See
+[`docs/how-to/installation.md`](docs/how-to/installation.md) for details.
+
+## Usage
+
+```bash
+hhemt --help          # CLI entry point
+```
+
+See the [documentation](https://hhemt.readthedocs.io) for the end-to-end
+analysis workflow.
+
+## How to cite
+
+If you use this software, please cite it. Citation metadata is maintained in [`CITATION.cff`](CITATION.cff) (GitHub's "Cite this repository" resolves it). Once the first release is published, cite the specific version via its Zenodo DOI:
+
+<!-- The Zenodo concept-DOI badge is added when the first release DOI is minted (first-public-release):
+[![DOI](https://zenodo.org/badge/DOI/PLACEHOLDER.svg)](https://doi.org/PLACEHOLDER) -->
+
+## Credits
+
+This package was created with [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) and the [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) project template.

hhemt-0.1.0/docs/explanation/branching-and-release-model.md

@@ -0,0 +1,37 @@
+# Branching and release model
+
+This project uses a **gitflow-lite** model: a long-lived development branch (`develop`) that is the GitHub default, and a release-only `main` that advances only through validated releases.
+
+## The two branches
+
+- **`develop`** — the GitHub **default branch** and the primary local checkout. All day-to-day work happens here. Feature/worktree branches are created *from* `develop` and merged *back* into it. Read-the-Docs "latest" builds `develop`.
+- **`main`** — **release-only**. `main` advances *only* via a `develop` → `main` release pull request that passes the release gate (all tests green, docs accurate and complete). Every release merge is tagged `vX.Y.Z`. Read-the-Docs "stable" builds the latest tag, so public visitors land on released docs.
+
+A GitHub **ruleset** on `main` enforces this: pull-request-required-before-merge, linear history, `squash`/`rebase` merges only, and blocked force-pushes/deletions. The required status checks that gate a release PR (full test suite, docs build, CITATION.cff validation, identifier-blocklist guard) are configured separately as part of the release gate. The LAYOUT_VERSION check is NOT a required status check: it runs only under pre-commit (against `HEAD~1`), so layout-version discipline is enforced at `develop`-commit time and inherited by the release (see "Two independent version axes").
+
+## Worktree workflow (unchanged)
+
+The per-branch worktree workflow is unaffected by this model. Worktrees branch from the primary checkout's `HEAD`, so with the primary checkout on `develop`, new worktrees branch from `develop` automatically. Staging discipline and merge-back are branch-name-agnostic.
+
+## Cutting a release
+
+Releases are executed with the `/release-project` workflow, which opens the `develop` → `main` PR, verifies every required status check is green, merges, and tags the post-merge `main` commit `vX.Y.Z` (the tag — not `develop`'s tip — is what fires the PyPI publish and the Zenodo DOI mint). Never tag `develop`'s tip: that would publish an un-gated commit.
+
+## Read-the-Docs "stable" default (operator runbook)
+
+Read-the-Docs maps versions to branches/tags in the **project dashboard**, not in `.readthedocs.yaml`. Once the first `vX.Y.Z` tag exists, set the default version to **stable** so public visitors land on released docs:
+
+1. Read-the-Docs dashboard → the `hhemt` project → **Admin → Settings**.
+2. Set **Default version** to `stable`.
+3. Confirm the `stable` version is **Active** under **Admin → Versions** (it is auto-created from the highest `vX.Y.Z` tag).
+
+Until the first tag exists, `stable` has no build target — leave the default at `latest` (which tracks `develop`). This flip is performed at the first public release.
+
+## Two independent version axes
+
+Do not conflate these:
+
+- **On-disk layout version** — `LAYOUT_VERSION` (`src/hhemt/version_migration/constants.py`), a monotonic integer governing on-disk analysis-tree/system-directory compatibility. Bumping it requires a migration module + golden fixtures (CI Check A/B, enforced at commit time via pre-commit, not in GitHub Actions).
+- **Software release version** — the SemVer in `pyproject.toml` and the `vX.Y.Z` git tag, governing the PyPI/release artifact.
+
+A release tag never touches `LAYOUT_VERSION`; a `LAYOUT_VERSION` bump never touches the SemVer. Because `check_layout_version.py` runs only under pre-commit (against `HEAD~1`) and is not wired into any GitHub Actions workflow, a release merge does not re-trigger the layout checks — the release inherits whatever `develop` already validated.

hhemt-0.1.0/docs/explanation/capabilities.md

@@ -0,0 +1,28 @@
+# Capabilities
+
+The H&H Ensemble Modeling Toolkit (hhemt) orchestrates coupled TRITON-SWMM flood simulations as embarrassingly-parallel ensembles across local workstations and HPC clusters, using configurable CPU or GPU resources per simulation on both NVIDIA and AMD hardware. It manages the full lifecycle — preprocessing, compilation, execution, and post-processing — producing analysis-ready datasets and an interactive report.
+
+## Three classes of study
+
+From a single codebase, the toolkit makes three classes of study tractable: **model comparison** across TRITON, SWMM, and the coupled TRITON-SWMM; **ensemble flood studies** over many events; and **sensitivity analysis**, including the fully built-out benchmarking study type. A fourth, cross-cutting capability — **hardware portability** — lets any of these run unchanged on CPU or on NVIDIA or AMD GPUs, on a workstation or on HPC.
+
+## Model comparison across TRITON, SWMM, and coupled TRITON-SWMM
+
+The toolkit compiles and runs any combination of the three model types — TRITON alone, SWMM alone, or the coupled TRITON-SWMM — as independently toggled options, keeping each model's outputs in its own store. Running the same event through more than one model produces a direct intermodel comparison, so you can measure how much the tight two-way coupling between surface flooding and stormwater hydraulics changes results — and decide whether the added cost of coupling is warranted.
+
+## Ensemble flood studies
+
+The toolkit parallelizes simulations rather than running them in sequence, so large ensembles of events — for flood studies and uncertainty assessment — are tractable. Outputs consolidate into hierarchical `DataTree` zarr stores stamped with CF-1.13 conventions, ready for objective-function computation and analysis across the full population of simulated events. Snakemake, the open-source workflow manager, maximizes utilization of the allocated resources and skips work that has already completed, so re-running an analysis never repeats finished steps.
+
+## Hardware portability
+
+GPU code compiles against either the CUDA (NVIDIA) or HIP/ROCm (AMD) backend, selected through configuration YAML files; CPU-only execution is also supported. The toolkit runs on both ORNL's Frontier (AMD) and UVA's Rivanna (NVIDIA), which both use the SLURM scheduler. It can run a large ensemble as one big SLURM allocation (typical on Frontier) or as a batch of many fit-to-purpose SLURM jobs, one per workflow step (typical on Rivanna).
+
+## Sensitivity analysis and benchmarking
+
+A parameter table you provide turns each row into a modeled scenario, so almost any input can be varied across a study — the SWMM hydraulic model, Manning's roughness, the grid resolution, and the compute configuration among them. Benchmarking is the first fully built-out sensitivity-analysis type: it produces a report with standard verification metrics and hydraulic-output visualizations, plus benchmarking-specific figures for run time, compute cost, and strong-scaling speedup. Run a benchmarking study on your own machine or HPC system to find the compute configuration that best fits your hardware and the system you intend to simulate.
+
+## See also
+
+- [Quickstart](../tutorials/quickstart.md) — try it.
+- [Example interactive report](../reference/example-report.md) — see a rendered report.

hhemt-0.1.0/docs/explanation/index.md

@@ -0,0 +1,13 @@
+# Explanation
+
+Understanding-oriented discussion: the concepts, capabilities, and design
+rationale behind the toolkit.
+
+- [Capabilities](capabilities.md) — what the toolkit does and the study
+  designs it supports.
+- [Software availability](software-availability.md) — licensing and how to
+  obtain the coupled solvers.
+- [When and why re-runs happen](rerun-faq.md) — the Snakemake re-run triggers
+  and the cases that surprise people.
+- [Branching and release model](branching-and-release-model.md) — the
+  `develop`/`main` gitflow-lite model.

hhemt-0.1.0/docs/explanation/rerun-faq.md

@@ -0,0 +1,59 @@
+# When and why re-runs happen
+
+hhemt drives its workflow with [Snakemake](https://snakemake.readthedocs.io/),
+so a step re-runs when one of three things changes: an input file's
+modification time (mtime), the *set* of declared inputs for a rule, or the
+rule's code. Most of the time this is exactly what you want — edit a config,
+re-run, and only the affected steps rebuild. This page explains the cases that
+surprise people. To *deliberately* force or suppress a re-run, see
+[Forcing and suppressing re-runs](../how-to/forcing-reruns.md).
+
+## The three trigger classes
+
+A rule re-runs when Snakemake detects any of:
+
+1. **Input mtime** — a file the rule declares as input is newer than the
+   output it produced. Editing a DEM, a weather file, or a SWMM template
+   re-runs the steps downstream of it.
+2. **Input-set change** — the *list* of declared inputs changed, even if no
+   file content did. When a toolkit release adds a new declared input to a
+   rule (for example, a per-scenario fingerprint file), Snakemake sees the
+   changed input set and re-runs that rule once.
+3. **Rule code change** — the `shell:`/`run:` body of a rule changed between
+   toolkit versions.
+
+The toolkit is designed so that steady-state re-invocations are cheap: once a
+phase is complete, its status flag and per-model log record the success, and a
+re-run of `analysis.run()` resumes rather than rebuilds.
+
+## Surprising cases
+
+??? question "I edited the sensitivity XLSX — what re-runs?"
+    The `sensitivity_analysis_definition.csv` is re-derived from the XLSX on
+    **every** `analysis.run()`, and only the touched `sa_id` chains re-run.
+    Editing the CSV directly is a no-op — it is silently overwritten before
+    Snakemake plans, so the run reports "resuming, N/N complete" even though
+    you expected a new row. Always edit the XLSX, not the derived CSV.
+
+??? question "I removed a row (sa_id) from the XLSX — why did it abort?"
+    Removing an `sa_id` leaves an orphan `subanalyses/sa_*/` directory on disk.
+    The toolkit detects the orphan and `analysis.run()` **aborts** with a
+    `ConfigurationError` rather than silently deleting data. Re-invoke with
+    `cleanup_orphans=True` (or run `hhemt cleanup-orphans --apply --force`) to
+    delete the orphan artifacts. Deletion is opt-in because it is
+    irrecoverable.
+
+??? question "Everything re-ran once after I upgraded the toolkit — is that a bug?"
+    No — this is the expected one-shot cascade. The first `analysis.run()`
+    after a release that changes a rule's declared input set, a rule's code,
+    or a plot-ID grammar invalidates Snakemake's metadata and re-fires the
+    affected rules exactly once. Steady state resumes on the second
+    invocation, producing no observable artifact change. A single full rebuild
+    right after an upgrade is normal, not a defect.
+
+??? question "I re-ran and nothing happened, but I expected a rebuild."
+    Completion is tracked by `_status/*.flag` markers plus per-model log
+    success records, not by file presence alone. If a flag survives, the step
+    is considered done and is skipped. To force a specific step to rebuild
+    regardless of its flag, use the override knobs described in
+    [Forcing and suppressing re-runs](../how-to/forcing-reruns.md).

hhemt-0.1.0/docs/explanation/software-availability.md

@@ -0,0 +1,13 @@
+# Software availability and reproducibility
+
+The H&H Ensemble Modeling Toolkit (hhemt) is publicly available at <https://github.com/lassiterdc/hhemt> and on PyPI (`pip install hhemt`).
+
+**License.** Released under [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) — free for any noncommercial purpose (see `LICENSE`).
+
+**How to cite.** Cite the software via its Zenodo DOI (see the repository's "How to cite" section and `CITATION.cff`).
+
+**Reproducibility.** The environment is reproduced from `environment.yaml` (`conda env create`); the toolkit installs on top via `pip install -e .`. Two test tiers guard regressions: a fast synthetic tier and a real-data tier built on the Norfolk, VA case study.
+
+**Data availability.** The Norfolk case-study inputs are published on HydroShare and download anonymously via the toolkit's integrated `case.yaml` path.
+
+**Reproduce the release.** Install → get the Norfolk data → run a predefined experiment → smoke-test with `analysis.test()`. See the [Norfolk end-to-end tutorial](../tutorials/norfolk-end-to-end.md).